Help:General concepts

From canasta

General concepts

This page covers foundational concepts that apply to all Canasta installations, 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, especially if Elasticsearch is enabled.

Installation IDs

Every Canasta installation has an installation ID — a name you choose when creating it with the -i flag: 

canasta create -i myinstance -w main -n localhost

The installation ID is used to refer to the installation in all subsequent commands: 

canasta start -i myinstance
canasta extension list -i myinstance

The -i flag is required for canasta create (since the installation directory doesn't exist yet). For all other commands, -i is optional if you run the command from within the installation directory or any of its subdirectories (e.g., config/settings/).

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

Wiki IDs

Every wiki in a Canasta installation 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 localhost

Even a single-wiki installation 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 installation IDs). The names settings, images, w, and wiki are reserved. See Wiki ID naming rules for details.

Installation directory structure

After creating a Canasta installation, the directory contains: 

{installation-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 installations 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 installation registry: 

export CANASTA_CONFIG_DIR=/shared/canasta-config

The directory is created automatically if it does not exist.

Example: 

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

wikis.yaml

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

wikis:
- id: main
  url: localhost
  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).

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 Deploying behind a reverse proxy.

Settings

Settings files are PHP files placed in the settings directories and loaded in lexicographic order:

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

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

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).

Configuring logos

MediaWiki uses the $wgLogos configuration variable to set the wiki logo. See the MediaWiki documentation for details on logo sizes and formats.

There are two approaches to configuring logos in Canasta, depending on whether you want the logo to follow wiki permissions or be publicly accessible.

Option 1: Public assets directory (recommended for most cases)

Place your logo in the public_assets/ directory. This directory is organized by wiki ID, so each wiki has its own subdirectory: 

cp /path/to/logo.png public_assets/{wiki-id}/logo.png

Then configure it in a per-wiki settings file: 

<?php
# config/settings/wikis/{wiki-id}/Logo.php

$wgLogos = [
    '1x' => "/public_assets/logo.png",
];

The URL /public_assets/logo.png is automatically routed to the correct wiki's subdirectory based on the request's domain or path.

This approach:

  • Always publicly accessible — works for both public and private wikis
  • Works for wiki farms — each wiki has its own subdirectory
  • Fast — served as static files without MediaWiki overhead
  • Persists across upgrades — stored in a mounted volume

Use this option for private wikis that need a visible logo on the login page, or any wiki where you want fast, public access to the logo.

Option 2: Upload via MediaWiki

Upload your logo through MediaWiki's Special:Upload page, then reference it in a settings file: 

<?php
# config/settings/wikis/{wiki-id}/Logo.php

$wgLogos = [
    '1x' => $wgUploadPath . '/Logo.png',
];

This approach:

  • Follows wiki permissions — on public wikis, anyone can see the logo; on private wikis, only logged-in users can see it
  • Works for wiki farms — each wiki uploads its own logo
  • Persists across upgrades — uploaded files are stored in the images/ directory

Use this option for fully private wikis where the logo should not be visible to logged-out users.

Summary

Scenario Solution
Public wiki Either option works
Private wiki, logo visible on login page Public assets directory
Private wiki, logo hidden from logged-out users Upload via MediaWiki

Importing an existing wiki

To migrate an existing MediaWiki installation into Canasta, prepare a database dump (.sql or .sql.gz file) and pass it with the -d flag: 

canasta create -i myinstance -w main -n localhost -d ./backup.sql.gz

You can also provide a per-wiki settings file and an environment file with password overrides: 

canasta create -i myinstance -w main -n localhost -d ./backup.sql.gz -l ./my-settings.php -e ./custom.env

The -l flag (--wiki-settings) copies the specified file to config/settings/wikis/{wiki-id}/, preserving the filename. Use it to bring over custom settings from an existing wiki.

To import a database into an additional wiki in an existing installation, use canasta add with the --database flag: 

canasta add -i myinstance -w docs -u example.com/docs -d ./docs-backup.sql.gz

See the CLI Reference for the full list of flags.

Maintenance scripts

MediaWiki includes over 200 maintenance scripts for tasks like changing passwords, importing images, and managing the database.

Automatic maintenance

You generally do not need to run maintenance scripts manually:

  • update.php runs automatically during container startup. If you need to run it, simply restart the installation with canasta restart.
  • runJobs.php runs automatically in the background for the entire life of the container.

Running the update sequence

Use canasta maintenance update to run the standard update sequence: update.php, runJobs.php, and (if Semantic MediaWiki is installed) rebuildData.php. Each script runs separately with its output streamed in real time. 

canasta maintenance update -i myinstance

In a wiki farm, use --wiki to target a specific wiki or --all to run on every wiki: 

canasta maintenance update -i myinstance --wiki=docs
canasta maintenance update -i myinstance --all

If the installation has only one wiki, it is selected automatically. If there are multiple wikis and neither --wiki nor --all is specified, the command will error with guidance.

Use --skip-jobs and --skip-smw to skip individual steps: 

# Run only update.php
canasta maintenance update -i myinstance --skip-jobs --skip-smw

Running scripts manually

To run an arbitrary MediaWiki core maintenance script, use canasta maintenance script. Wrap the script name and any arguments in quotes so they are passed as a single argument: 

canasta maintenance script "createAndPromote.php WikiSysop MyPassword --bureaucrat --sysop" -i myinstance

To list all available core maintenance scripts: 

canasta maintenance script -i myinstance

Use --wiki to target a specific wiki in a farm: 

canasta maintenance script "rebuildrecentchanges.php" -i myinstance --wiki=docs

Running extension maintenance scripts

Many extensions include their own maintenance scripts (e.g., Semantic MediaWiki, CirrusSearch, Cargo). Use canasta maintenance extension to discover and run them.

List all loaded extensions that have maintenance scripts: 

canasta maintenance extension -i myinstance

List available scripts for a specific extension: 

canasta maintenance extension -i myinstance SemanticMediaWiki

Run an extension maintenance script. Flags (-i, --wiki, --all) come before the extension name; everything after is the script and its arguments — no quotes needed: 

canasta maintenance extension -i myinstance SemanticMediaWiki rebuildData.php
canasta maintenance extension -i myinstance CirrusSearch UpdateSearchIndexConfig.php --reindexAndRemoveOk --indexIdentifier now

For large operations, pass script-specific options directly: 

canasta maintenance extension -i myinstance SemanticMediaWiki rebuildData.php -s 1000 -e 2000

Use --wiki and --all for wiki farms, just like other maintenance commands: 

canasta maintenance extension -i myinstance --wiki=docs SemanticMediaWiki rebuildData.php
canasta maintenance extension -i myinstance --all SemanticMediaWiki rebuildData.php

Only extensions that are currently loaded (enabled) for the target wiki are shown and can be run.

See the CLI Reference for more details.

Sitemaps

XML sitemaps help search engines discover and index pages on your wiki. See the Sitemaps guide for full details on generating, removing, and troubleshooting sitemaps.

Custom Canasta images

By default, canasta create uses the latest published Canasta image (ghcr.io/canastawiki/canasta:latest). 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 localhost\
  --canasta-image ghcr.io/canastawiki/canasta:version-3.0.7

This writes CANASTA_IMAGE to the installation'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.

Deploying behind a reverse proxy

When running Canasta behind an external reverse proxy that terminates SSL and forwards requests to Canasta over HTTP (such as nginx, a cloud load balancer, or Cloudflare in "Flexible SSL" mode), you must tell Caddy to serve over HTTP only. Otherwise, Caddy will attempt to provision certificates and listen on HTTPS, causing redirect loops or connection errors.

For a new installation, create an env file with the setting and pass it to canasta create: 

CADDY_AUTO_HTTPS=off

canasta create -i myinstance -w main -n example.com -e custom.env

This generates a Caddyfile with http:// site addresses so Caddy listens on port 80 only.

For an existing installation: 

canasta config set -i myinstance CADDY_AUTO_HTTPS=off

To re-enable automatic HTTPS (e.g., if you move the wiki off the reverse proxy): 

canasta config unset -i myinstance CADDY_AUTO_HTTPS

Running on non-standard ports

By default, Canasta uses ports 80 (HTTP) and 443 (HTTPS). To use different ports — for example, to run multiple Canasta installations on the same server — the approach depends on whether you are creating a new installation or changing an existing one.

New installation

Pass an env file with port settings to canasta create. Create a file called custom.env: 

HTTP_PORT=8080
HTTPS_PORT=8443

canasta create -i staging -w testwiki -n localhost:8443 -e custom.env

Existing installation

Use canasta config set. Multiple settings can be changed in a single command. The HTTPS_PORT side effect automatically updates config/wikis.yaml URLs, MW_SITE_SERVER, and MW_SITE_FQDN to match: 

canasta config set -i myinstance HTTP_PORT=8080 HTTPS_PORT=8443

To revert to the default ports (80/443), remove the overrides: 

canasta config unset -i myinstance HTTP_PORT HTTPS_PORT

Example: multiple installations on the same machine

Each installation must use unique ports. This applies to both Docker Compose and Kubernetes (--create-cluster) installations — they can be mixed freely. 

# Docker Compose installation on default ports (80/443)
canasta create -i production -w mainwiki -n localhost
# Docker Compose installation on custom ports
canasta create -i staging -w testwiki -n localhost:8443 -e custom.env

# Local Kubernetes installation on different custom ports
canasta create -o k8s --create-cluster -i dev-k8s -w devwiki -n localhost:9443 -e another.env

Access them at https://localhost, https://localhost:8443, and https://localhost:9443.

TLS certificates and non-standard ports

When Canasta is configured with a real domain name, Caddy automatically obtains a TLS certificate from Let's Encrypt. This uses the ACME HTTP-01 challenge, which requires Let's Encrypt to connect to port 80 on your server. If you set HTTP_PORT to a non-standard value, the challenge will fail because Let's Encrypt cannot reach Caddy on port 80.

Non-standard ports are therefore intended for local development and testing (e.g., localhost:8443), not for production deployments with automatic TLS.

If you need to run multiple Canasta installations with TLS on the same server, place a shared reverse proxy (such as Caddy or nginx) in front of all instances. The reverse proxy holds ports 80/443, obtains the certificates, and forwards traffic to each Canasta instance on its internal ports. In this setup, each Canasta instance should set CADDY_AUTO_HTTPS=off in its .env file so its built-in Caddy does not attempt its own ACME challenges.

Changing the domain name

The domain name for each wiki is stored in config/wikis.yaml. The .env file also contains two domain-related variables:

  • MW_SITE_SERVER — the full URL of the primary wiki (e.g., https://example.com)
  • MW_SITE_FQDN — the domain name of the primary wiki (e.g., example.com)

These refer specifically to the primary (first) wiki in the installation. In a wiki farm, additional wikis may use the same domain (path-based) or different domains (subdomain-based), and their URLs are managed entirely in wikis.yaml.

Single wiki or path-based farm

When all wikis share the same domain, changing the domain requires updating both wikis.yaml and .env:

  1. Edit config/wikis.yaml and update the url field for each wiki:
   wikis:
   - id: main
     url: newdomain.example.com
     name: main
   - id: docs
     url: newdomain.example.com/docs
     name: docs
  1. Update the .env variables to match and restart:
   canasta config set -i myinstance MW_SITE_SERVER=https://newdomain.example.com MW_SITE_FQDN=newdomain.example.com

  This triggers a restart, which regenerates the Caddyfile from the updated wikis.yaml.

Subdomain-based farm

When wikis use different subdomains, you only need to update MW_SITE_SERVER and MW_SITE_FQDN if the primary wiki's domain is changing. To change another wiki's domain, edit its url in wikis.yaml and restart: 

canasta restart -i myinstance

Port changes

If you are also changing the port, use canasta config set HTTPS_PORT=<port> instead — it updates wikis.yaml, MW_SITE_SERVER, and MW_SITE_FQDN automatically. See Running on non-standard ports.

Retrieved from "https://canasta.wiki/w/index.php?title=Help:General_concepts&oldid=20"
Powered by MediaWiki
Powered by Canasta