canasta config

View and modify Canasta configuration

Synopsis

View and modify the .env configuration for a Canasta instance.

Use canasta config get to view current settings and canasta config set to change them. The set command handles side effects automatically (e.g., updating wikis.yaml when changing HTTPS_PORT) and restarts the instance. Editing .env by hand may leave the instance in an inconsistent state.

Key names are case-insensitive and hyphens are treated as underscores, so https-port, HTTPS_PORT, and Https_Port all work.

Settings safe to change on a running instance:

  Database
    MYSQL_PASSWORD                    Database administrator (root) password; on the bundled database, setting it changes the password in the database too
    WIKI_DB_PASSWORD                  Password of MediaWiki's own database account; setting it changes the account's password at the restart
    WIKI_DB_USER                      Database account MediaWiki connects as, set by create and upgrade; to keep MediaWiki on root, set CANASTA_DB_ROOT_ACCOUNT instead
    CANASTA_DB_ROOT_ACCOUNT           true keeps MediaWiki on the database administrator account instead of its own, and stops upgrades moving it (default: false)

  Network
    HTTP_PORT                         HTTP port the HAProxy edge serves the instance on (default: 80)
    HTTPS_PORT                        HTTPS port the HAProxy edge serves the instance on (default: 443)

  PHP
    PHP_UPLOAD_MAX_FILESIZE           Upload file size limit (default: 10M)
    PHP_POST_MAX_SIZE                 POST data size limit (default: 10M)
    PHP_MAX_INPUT_VARS                Max input variables (default: 1000)

  Sitemaps
    MW_SITEMAP_PAUSE_DAYS             Days between sitemap refreshes (default: 1)

  Maintenance scripts
    MW_ENABLE_JOB_RUNNER              Run the background job runner (default: true)
    MW_JOB_RUNNER_PAUSE               Seconds the job runner sleeps between passes (default: 2)
    MW_JOB_RUNNER_MEMORY_LIMIT        Memory limit for runJobs.php (default: 512M)
    MW_ENABLE_TRANSCODER              Run the video transcoder job runner (default: true)
    MW_JOB_TRANSCODER_PAUSE           Seconds the transcoder runner sleeps between passes (default: 60)
    MW_ENABLE_LOG_ROTATOR             Run the log rotator (default: true)
    MW_AUTOUPDATE                     Run update.php on container start (default: true)

  Features
    CANASTA_ENABLE_CROWDSEC           Enable CrowdSec behavioral threat detection (default: false)
    CANASTA_ENABLE_ELASTICSEARCH      Enable Elasticsearch (default: false)
    CANASTA_ENABLE_OBSERVABILITY      Enable observability stack (default: false)
    CANASTA_ENABLE_VARNISH            Enable Varnish caching (default: true)
    CANASTA_ENABLE_WIKI_DIRECTORY     Show wiki directory on 404 pages (default: false)
    CANASTA_ENABLE_VERY_SHORT_URLS    Use /wiki/Page (no /w/) URLs (default: false)

  MediaWiki site
    MW_SITE_SERVER                    Site URL (e.g., https://example.com)
    MW_SITE_FQDN                      Domain name (e.g., example.com)

  TLS
    CANASTA_STAGING_CERTS             Use Let's Encrypt staging CA (untrusted, but avoids rate limits) (default: false)
    TLS_MODE                          How the HAProxy edge serves the instance on Docker Compose. "acme" (default) gets certificates from Let's Encrypt. "acme-dns" uses Let's Encrypt with DNS validation through ACME_DNS_PROVIDER. "internal" issues them from the edge's own CA, for a CDN that does not validate the origin certificate. "custom" serves TLS_CERT and TLS_KEY from config/certs/. "off" serves the instance over plain HTTP on its HTTP_PORT, behind your own TLS-terminating proxy. (default: acme)
    TLS_CERT                          Certificate filename within config/certs/, used when TLS_MODE is "custom". config/certs/ is gitignored, so a private key placed there never reaches the gitops repository. (default: origin.crt)
    TLS_KEY                           Private key filename within config/certs/, used when TLS_MODE is "custom". (default: origin.key)
    TRUSTED_PROXIES                   The CDN or proxy in front of the instance, whose client-address header to trust: "cloudflare", "imperva", or a comma-separated CIDR list of proxies whose X-Forwarded-For to trust. Unset = nothing in front (default).
    ACME_DNS_PROVIDER                 DNS provider for TLS_MODE=acme-dns. The supported provider is "cloudflare" (the default), which uses CLOUDFLARE_API_TOKEN. (default: cloudflare)
    CLOUDFLARE_API_TOKEN              Cloudflare API token with DNS edit permission for the instance's zone, used by TLS_MODE=acme-dns
    CLOUDFLARE_ZONE_ID                Cloudflare zone ID for TLS_MODE=acme-dns; keeps the token with the instance's certificates, so instances with different tokens can share the edge

  HAProxy edge
    CANASTA_EDGE_RATE_DYNAMIC         Requests one client may make in 10 seconds that always reach PHP (API, Special pages, logged-in views) before the edge answers 429; 0 turns the limit off (default: 60)
    CANASTA_EDGE_RATE_DEFAULT         Page views one client may request in 10 seconds before the edge answers 429; 0 turns the limit off (default: 300)
    CANASTA_EDGE_DYNAMIC_MAXCONN      Concurrent requests that always reach PHP the edge passes to the instance; more wait in a queue. Defaults to 60% of PM_MAX_CHILDREN
    CANASTA_EDGE_DEFAULT_MAXCONN      Concurrent page views the edge passes to the instance; more wait in a queue. Defaults to 8 times PM_MAX_CHILDREN (2 times without Varnish)
    CANASTA_EDGE_MEDIA_MAXCONN        Concurrent requests for the instance's media hostnames the edge passes on; more wait in a queue. Media hostnames are not rate-limited per client, since they never reach PHP (default: 500)

  Caddy
    CADDY_TRUSTED_PROXY_CIDRS         Kubernetes only. Comma-separated CIDRs of the in-cluster ingress to trust so Caddy reads the real client IP. Defaults to the standard private ranges (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16); override only for a non-default pod/service CIDR. On Compose, applies behind the HAProxy edge.

  Docker Image
    CANASTA_IMAGE                     Override the default Canasta image
    CANASTA_ELASTICSEARCH_IMAGE       Override the Elasticsearch image (e.g. a build with an extra analysis plugin). Takes effect only while Elasticsearch is enabled (CANASTA_ENABLE_ELASTICSEARCH=true). On Kubernetes the image must be pullable by the cluster (push it to a reachable registry first).

  Security (CrowdSec)
    CROWDSEC_BOUNCER_API_KEY          Caddy bouncer API key from 'cscli bouncers add'. Optional; the bouncer stays dormant (blocks nothing) until it is set.
    CROWDSEC_SPOA_API_KEY             API key of the instance's CrowdSec bouncer at the HAProxy edge, from 'cscli bouncers add'. Registered and stored automatically when an instance with CrowdSec is behind the edge; until it is set, the edge does not check this instance's clients with CrowdSec.
    CROWDSEC_AGENT_PASSWORD           Kubernetes only. Password the CrowdSec agent in the caddy pod logs in to the local API with. Generated when CrowdSec is enabled; changing it restarts both pods on the next deploy.

  Backup (Restic)
    RESTIC_REPOSITORY                 Restic repo URL or local path
    RESTIC_PASSWORD                   Restic repo password

Restic backups also accept any backend-specific credentials whose keys start with AWS_, AZURE_, B2_, GOOGLE_, OS_, ST_, or RCLONE_ (e.g. AWS_ACCESS_KEY_ID for S3, AZURE_ACCOUNT_NAME for Azure, B2_ACCOUNT_ID for Backblaze). The entire .env is passed to the Restic container, so any variable Restic recognizes will work — see https://restic.readthedocs.io/en/stable/040_backup.html . SMTP credentials (SMTP_*) are also accepted.

Other settings (database passwords, secret keys, etc.) are generated by canasta create and should not be changed directly. To change the domain, first edit config/wikis.yaml, then use canasta config set to update MW_SITE_SERVER and MW_SITE_FQDN.

Subcommands

This command requires a subcommand:

get — Show configuration settings
refresh-template — List, diff, or adopt template versions of seeded config files
set — Change configuration values
unset — Remove a configuration setting

Global flags

Flag	Shorthand	Description	Default	Required	Orchestrator
`--help`	`-h`	Show help message and exit			Both
`--verbose`	`-v`	Enable verbose output			Both