General concepts

This page covers foundational concepts that apply to all Canasta instances, whether hosting a single wiki or a wiki farm.

System requirements

Canasta requires at least 4 GB of available memory to run. The canasta create command checks available memory before proceeding and will exit with an error if the system does not meet this requirement.

For production use, 8 GB or more of total system memory is recommended. Both Elasticsearch (for CirrusSearch) and the observability stack (OpenSearch + Logstash) are optional containers that are memory-intensive. If you enable both, 16 GB or more is recommended.

Instance IDs

Every Canasta instance (also referred to as a wiki farm, even if it contains only one wiki) has an instance ID — a name you choose when creating it with the -i flag:

canasta create -i myinstance -w main -n example.com

The instance ID is used to refer to the instance in subsequent commands:

canasta start -i myinstance
canasta extension list -i myinstance

Instance IDs must start and end with an alphanumeric character and may contain letters, digits, hyphens (-), and underscores (_).

Tip: The -i flag is only required for canasta create (since the instance directory doesn't exist yet). For all other commands, you can omit -i if you run the command from within the instance directory or any of its subdirectories. Examples on this wiki use the short form without -i.

Wiki IDs

Every wiki in a Canasta instance has a wiki ID — a short identifier set with the -w flag when creating or adding a wiki:

canasta create -i myinstance -w main -n example.com

Even a single-wiki instance requires a wiki ID. The wiki ID is used as:

• The MariaDB database name for that wiki
• The directory name under config/settings/wikis/
• The suffix in the admin password file (config/admin-password_{wikiid})
• The value passed to -w in commands like canasta extension, canasta remove, and canasta export

Wiki IDs may contain only alphanumeric characters and underscores. Hyphens are not allowed (unlike instance IDs). The names settings, images, w, and wiki are reserved. See Wiki ID naming rules for details.

Instance directory structure

After creating a Canasta instance, the directory contains:

{instance-path}/
├── .env                           # Environment variables (domain, DB passwords, secret key)
├── docker-compose.yml             # Docker Compose configuration
├── docker-compose.override.yml    # Optional custom overrides
├── config/
│   ├── wikis.yaml                 # Wiki definition (IDs, URLs, display names)
│   ├── Caddyfile                  # Generated reverse proxy config (do not edit)
│   ├── Caddyfile.site             # User customizations for Caddy site block
│   ├── Caddyfile.global           # User global options and extra site blocks
│   ├── admin-password_{wiki-id}   # Generated admin password per wiki
│   └── settings/
│       ├── global/                # PHP settings loaded for all wikis
│       │   └── *.php
│       └── wikis/
│           └── {wiki-id}/         # PHP settings loaded for a specific wiki
│               └── *.php
├── extensions/                    # User extensions
├── skins/                         # User skins
├── images/                        # Uploaded files
└── public_assets/                 # Publicly accessible files (logos, etc.)

conf.json

The CLI maintains a registry of all instances in a conf.json file. The location depends on the platform:

• Linux (root): /etc/canasta/conf.json
• Linux (non-root): ~/.config/canasta/conf.json
• macOS: ~/Library/Application Support/canasta/conf.json

To override the default location, set the CANASTA_CONFIG_DIR environment variable. This takes priority over the platform defaults and is useful when multiple sysops need to share a single instance registry:

export CANASTA_CONFIG_DIR=/shared/canasta-config

The directory is created automatically if it does not exist.

Example:

{
  "Orchestrators": {},
  "Instances": {
    "myinstance": {
      "Id": "myinstance",
      "Path": "/home/user/myinstance",
      "Orchestrator": "compose"
    }
  }
}

wikis.yaml

This file defines the wikis in the instance. Even a single-wiki instance has a wikis.yaml:

wikis:
- id: main
  url: example.com
  name: My Wiki

For a multi-wiki farm, it lists all wikis:

wikis:
- id: mainwiki
  url: example.com
  name: Main Wiki
- id: docs
  url: example.com/docs
  name: Documentation

The url field uses domain/path format without the protocol. The Caddyfile is regenerated from this file whenever wikis are added or removed.

Changing a wiki's display name

The name field in wikis.yaml controls the wiki's display name ($wgSitename in MediaWiki). It defaults to the wiki ID if not set. The name is initially set with the -t (--site-name) flag of canasta create or canasta add:

canasta create -i myinstance -w docs -n example.com -t "Project Documentation"

To change it later, edit the name field directly in config/wikis.yaml:

wikis:
- id: docs
  url: example.com/docs
  name: Project Documentation

The change takes effect immediately — no restart is needed.

Do not set $wgSitename in PHP settings files — it is configured automatically from wikis.yaml.

$wgMetaNamespace provides an alias for the Project namespace (the Project: prefix always works as well). It is derived from the display name with spaces replaced by underscores. For example, a wiki named "Project Documentation" will get the alias Project_Documentation:. If you need a different alias, you can override $wgMetaNamespace in a per-wiki settings file (use underscores instead of spaces).

Changing the domain name

The domain name is stored in config/wikis.yaml and the .env file (MW_SITE_SERVER, MW_SITE_FQDN). See Common tasks: Changing the domain name for step-by-step instructions for single wikis, path-based farms, and subdomain-based farms.

Caddyfile, Caddyfile.site, and Caddyfile.global

Canasta uses Caddy as its reverse proxy. The config/Caddyfile is auto-generated from wikis.yaml and is overwritten whenever wikis are added or removed — do not edit it directly.

To add custom Caddy directives for the site block (headers, rewrites, etc.), edit config/Caddyfile.site. To add global Caddy options or additional site blocks (e.g., a www-to-non-www redirect), edit config/Caddyfile.global. Both files are imported by the generated Caddyfile and are never overwritten.

Example Caddyfile.site:

header X-Frame-Options "SAMEORIGIN"
header X-Content-Type-Options "nosniff"

Example Caddyfile.global — redirect www.example.com to example.com so both domains reach the same wiki:

www.example.com {
    redir https://example.com{uri} permanent
}

See the Caddy documentation for available directives.

If deploying behind an external reverse proxy that handles SSL termination, see Common tasks: Deploying behind a reverse proxy.

Settings

Settings files are placed in the settings directories:

• Global settings (config/settings/global/) — loaded for every wiki
• Per-wiki settings (config/settings/wikis/{wiki-id}/) — loaded only for that wiki

This lets you configure shared behavior globally while customizing individual wikis where needed.

Loading order

Each settings directory can contain two types of files: YAML files and PHP files. Canasta loads them in the following order:

1. YAML files (*.yaml) — loaded in lexicographic order via MediaWiki's SettingsBuilder::loadFile()
2. PHP files (*.php) — loaded in lexicographic order via require_once

Global settings are loaded first, followed by per-wiki settings for the current wiki. Within each directory, the YAML-then-PHP order applies.

Both formats are valid ways to add settings. PHP files are useful for settings that require logic, function calls (such as enableSemantics()), or conditional expressions that YAML cannot represent. The YAML format supports extensions, skins, and configuration settings:

extensions:
- MyExtension
skins:
- MySkin

Since all settings files live in the mounted config/ volume, they persist across container restarts. Changes take effect on the next page load — no restart is required.

Note: YAML settings file loading relies on MediaWiki's SettingsBuilder API, which is still marked as unstable and may change in future MediaWiki versions. If the API changes, Canasta will be updated to match. PHP settings files are not affected by this and will always work.

Passwords

• Admin passwords are saved to config/admin-password_{wikiid} — one file per wiki
• Database passwords are saved to the .env file (MYSQL_PASSWORD for root, WIKI_DB_PASSWORD for the wiki user)

If not specified at creation time, passwords are auto-generated (30 characters with digits and symbols).

The Canasta stack

A Canasta instance is built from three components that are versioned and released independently:

• CanastaBase — the base Docker image. It contains the MediaWiki core software, the PHP runtime, and all bundled extensions and skins. When new Long Term Support (LTS) versions of MediaWiki are released, they are delivered through a new CanastaBase version.
• Canasta — a thin layer on top of CanastaBase that adds the Docker Compose and Kubernetes stack files, Caddy and Varnish configuration, and entry scripts. It inherits its extensions and skins from CanastaBase.
• Canasta CLI — the command-line tool that manages instances. The CLI version is independent of the Docker image version; canasta version shows both.

Running canasta upgrade updates all three components to the newest available versions.

Extension and skin versions

CanastaBase bundles over 170 extensions and skins. The specific version (commit) of each extension is determined by the RecommendedRevisions project — a community-maintained set of YAML files that list the recommended revision of each extension for each MediaWiki LTS version.

Canasta's contents.yaml file inherits from RecommendedRevisions, pinning each extension to a tested commit. This ensures that all bundled extensions are compatible with the MediaWiki version in the image. When building a custom image, you can override or extend contents.yaml to add, remove, or pin extensions differently.

Custom Canasta images

By default, canasta create uses the Canasta image version that the CLI was built for (e.g., ghcr.io/canastawiki/canasta:version-3.5.1). Each CLI release pins a specific image version to ensure compatibility. You can override this with the --canasta-image or --build-from flags, or by setting CANASTA_IMAGE in the .env file.

When to use a custom image

Scenario	Flag	Example
Use a specific published version or branch	--canasta-image	--canasta-image ghcr.io/canastawiki/canasta:version-3.0.7
Use an image from a private registry	--canasta-image	--canasta-image myregistry.io/canasta:v1.2.3
Test local changes to Canasta or CanastaBase	--build-from	--build-from ~/canasta-repos

--canasta-image

Specifies a full image reference to use instead of the default:

canasta create -i myinstance -w mywiki -n example.com\
  --canasta-image ghcr.io/canastawiki/canasta:version-3.0.7

This writes CANASTA_IMAGE to the instance's .env file so the stack uses the specified image.

--build-from

Builds Canasta (and optionally CanastaBase) from local source repositories. The directory must contain Canasta/; if CanastaBase/ is also present, it is built first and used as the base image. See Development mode: Building from local source for details.

--canasta-image and --build-from are mutually exclusive since --build-from builds its own image.

Orchestrator differences

Docker Compose: Both --canasta-image and --build-from work directly. Docker pulls or builds the image locally, and the Compose stack uses it.

Kubernetes: --canasta-image works as long as the image is pullable from the cluster (i.e., it's in a public registry or one the cluster has credentials for). --build-from requires extra image distribution: with --create-cluster (kind), the image is automatically loaded into the kind cluster; without it, the image is pushed to a registry specified by --registry so the cluster can pull it.

Caveats

• Upgrades are affected. When CANASTA_IMAGE is set in .env, canasta upgrade uses that image instead of pulling the default. If you want to return to the default image, remove the CANASTA_IMAGE line from .env and run canasta upgrade.
• MediaWiki version changes. If the custom image uses a different MediaWiki version than the previous image, update.php runs automatically on the next container start to apply database schema changes.
• Compatibility. Custom images should be based on CanastaBase to ensure the expected directory structure, entry scripts, and configuration mechanisms are present. Using an unrelated image will likely not work.

Containers

A Canasta instance runs several Docker containers. Some are always present; others are optional and can be enabled or disabled.

Required containers

• web — the main container running Apache, PHP, and MediaWiki. This is where all wiki requests are handled.
• db — MariaDB database server. Stores all wiki content, user accounts, and metadata.
• caddy — Caddy reverse proxy. Handles incoming HTTP/HTTPS traffic, automatic TLS certificate provisioning, and URL routing for wiki farms. Configuration is managed via config/Caddyfile (auto-generated) and config/Caddyfile.site / config/Caddyfile.global (user-editable).

Optional containers

• varnish — Varnish HTTP cache, sitting between Caddy and the web container. Caches anonymous page views to reduce load on MediaWiki. Enabled by default. To disable:

canasta config set CANASTA_ENABLE_VARNISH=false

• elasticsearch — powers the CirrusSearch extension for full-text search. Disabled by default; enable with canasta config set CANASTA_ENABLE_ELASTICSEARCH=true.
• opensearch and logstash — the observability stack. OpenSearch stores logs and Logstash ingests them. Disabled by default; see the Observability guide for setup.

The optional containers are memory-intensive. See System requirements for guidance on how much memory to allocate.