Wiki farms

What is a wiki farm?

A wiki farm is a single Canasta instance that hosts multiple wikis. All wikis in a farm share the same MediaWiki software, Docker containers, Caddy reverse proxy, and can share global PHP settings, extensions, and skins. At the same time, each wiki has its own:

Database — a separate MariaDB database named after the wiki ID
Image directory — uploaded files are stored per-wiki
Settings — each wiki can have its own PHP settings files and can enable or disable extensions and skins independently
Admin account — each wiki gets its own admin user and password

This makes wiki farms useful when you want to run several related wikis without the overhead of separate Docker stacks for each one, while still being able to configure each wiki individually where needed.

Even a single-wiki Canasta instance uses the same underlying architecture — it is simply a farm with one wiki. See General concepts for details on instance structure, wiki IDs, settings, and other topics that apply to all instances.

How wiki farm URLs work

Each wiki in a farm is identified by its URL, which determines how users reach it. The URL is set when you create or add a wiki and is stored in config/wikis.yaml.

Path-based wikis

Multiple wikis share the same domain, distinguished by URL path. The first wiki in the farm is created with canasta create and gets the root path. Additional wikis are added with canasta add using a domain/path URL:

# Create the farm with the first wiki at the root
canasta create -i myfarm -w mainwiki -n example.com
# Add a second wiki at example.com/docs
canasta add -w docs -u example.com/docs
# Add a third wiki at example.com/internal
canasta add -w internal -u example.com/internal

Users access these at https://example.com, https://example.com/docs, and https://example.com/internal.

Subdomain-based wikis

Each wiki uses a different subdomain. This requires DNS records pointing each subdomain to your Canasta server. Caddy handles SSL/HTTPS automatically for all configured domains.

canasta create -i myfarm -w mainwiki -n wiki.example.com
canasta add -w docs -u docs.example.com
canasta add -w community -u community.example.com

Mixed

You can combine both approaches:

canasta create -i myfarm -w mainwiki -n example.com
canasta add -w docs -u example.com/docs
canasta add -w community -u community.example.com

Creating a whole farm in one command

Instead of a create followed by one add per wiki, you can hand canasta create a ready-made wikis.yaml with -f/--yamlfile. Every wiki listed in the file gets its settings files, its database, and its own admin account in a single run, and -w becomes unnecessary:

canasta create -i myfarm -n example.com -f ./wikis.yaml

The file is copied verbatim to config/wikis.yaml, so it must use the same shape the CLI generates — a top-level wikis: key with unindented list entries:

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

Indenting the list entries under wikis: is valid YAML but is not what Canasta's parser expects, and the wikis will not be found. All the wikis share the one admin password reported at the end of create.

Managing a wiki farm

Viewing wikis

canasta list

Example output:

Canasta ID      Host              Instance Path
  Orchestrator  Status
  Wiki ID       Wiki URL
──────────────────────────────────────────────────────
myfarm          localhost         /home/user/myfarm
  COMPOSE       RUNNING
  mainwiki      example.com/
  docs          example.com/docs
  community     community.example.com/

Each instance is one block: its ID, host, and directory on the first line, then its orchestrator and status, then one line per wiki. Add --check-wikis to probe each wiki over HTTP and tag it in the output:

  mainwiki      example.com/  [REACHABLE]
  docs          example.com/docs  [REACHABLE]
  community     community.example.com/  [NOT REACHABLE]

Only RUNNING instances are probed. Use --host <name> to limit the listing to one host.

Per-wiki extension and skin management

Use the -w flag to target a specific wiki:

canasta extension enable SemanticMediaWiki -w docs
canasta skin enable CologneBlue -w community

Without -w, the command applies to all wikis in the farm.

Removing a wiki

canasta remove -w community

This deletes the wiki's database, per-wiki settings (config/settings/wikis/{id}/), uploaded files (images/{id}/), and public assets (public_assets/{id}/). You will be prompted for confirmation.

Deleting the entire farm

canasta delete

This stops and removes all containers, volumes, and configuration files.

Wiki directory

When a user browses to an unrecognized path on a wiki farm, Canasta returns a styled 404 page. You can optionally enable a wiki directory on this page, which displays a card grid of all wikis in the farm with links and logos.

The directory is disabled by default for security — enabling it publicly exposes the list of wikis in your farm.

Enabling the directory

canasta config set CANASTA_ENABLE_WIKI_DIRECTORY=true

After the instance restarts, the 404 page will show an "Available wikis" section with a card for each wiki. The directory is also available as a standalone landing page at the /wikis path (e.g. https://example.com/wikis).

Each card attempts to load the wiki's logo by querying its MediaWiki API. If a wiki is private, unreachable, or does not have a logo configured, the card appears without a logo. See Common tasks: Configuring logos for how to set up logos.

Disabling the directory

canasta config set CANASTA_ENABLE_WIKI_DIRECTORY=false

See the CLI Reference for the full list of commands and flags.