Sidecars

A sidecar is a companion service that runs alongside a Canasta instance and that the wiki talks to — for example a cache, a citation/parsing service, or a small application backend. Sidecars are declared once, in config/sidecars.yaml, using a single orchestrator-agnostic schema, and Canasta renders that declaration into the right runtime artifacts for whichever orchestrator the instance runs on: a Compose service layer on Docker Compose, Helm values on Kubernetes. The same declaration deploys identically on both.

Sidecars are managed with the canasta sidecar command group. They are a low-level building block: the commands manage the service (its container/pod, image, ports, storage, and the environment shared with the web tier), not any wiki-side configuration that uses it. Pointing MediaWiki at a sidecar — a $wg setting, an extension, a page — is done the normal way, in the instance's settings, and is independent of the sidecar declaration.

When to use a sidecar

Use a sidecar when the wiki needs a companion service running next to it. Typical cases: an in-memory cache (Redis/Valkey), a Citoid/citation service, a rendering or conversion microservice, or a custom application backend.

Do not use a sidecar for things Canasta already has first-class support for:

MediaWiki extensions and skins — see Help:Extensions and skins.
The optional CrowdSec security engine — see Help:CrowdSec (it is enabled with a config flag, not declared as a sidecar).
Replacing the bundled database with a managed one — see Help:External database.

Declaring sidecars

Sidecars live in config/sidecars.yaml in the instance directory. The file is one of: a single sidecar mapping, a list of mappings, or a top-level sidecars: list. Each entry uses the agnostic schema below.

sidecars:
  - name: cache
    image: redis:7-alpine
    command: redis-server --maxmemory ${REDIS_MAX_MEMORY:-100mb}
    ports: [6379]
    volumes:
      - name: data
        mountPath: /data
        persistent: true
        size: 1Gi

After editing config/sidecars.yaml (directly or through canasta sidecar add), run canasta restart to deploy the change.

Schema

Field	Meaning
`name`	Required. A DNS label. Other services (and the web tier) reach the sidecar by this name as its hostname.
`image`	Container image to run. Mutually exclusive with `build`.
`build`	Path to a build context (a directory with a `Dockerfile`) to build the image from, instead of pulling `image`. See #Building sidecar images.
`command`	Override the container command. `${VAR}` / `${VAR:-default}` references are resolved from the instance's `.env`.
`ports`	List of container ports the sidecar listens on. These are reachable by other services on the instance network (they are not published to the host).
`env`	Map of environment variables for the sidecar. Values may reference `.env` with `${VAR:-default}`. Variables referenced here that are also set in `.env` are bridged to the web tier — see #The web environment bridge.
`volumes`	List of volumes. Each has a `name` and `mountPath`; add `persistent: true` (with a `size`, e.g. `1Gi`) for durable storage, otherwise the volume is ephemeral.
`files`	List of in-repo config files to mount read-only into the sidecar. Each has a `source` (a path in the instance directory, version-controlled with the rest of the config), a `mountPath`, and optional `readOnly`.
`depends_on`	List of other sidecar names this one depends on for start ordering.
`healthcheck`	Either `{path, port}` for an HTTP check or `{tcp: port}` for a TCP check.
`resources`	Resource limits, in Kubernetes notation (e.g. `{memory: 512Mi}`). Canasta translates the notation for Compose automatically.

A richer example, using most of the schema:

sidecars:
  - name: citation
    image: example/citoid:1.0
    ports: [1970]
    depends_on: [translator]
    env:
      SHARED_SECRET: ${CITATION_SHARED_SECRET:-}
    files:
      - source: config/citation.yaml
        mountPath: /srv/config.yaml
        readOnly: true
    healthcheck:
      path: /_info
      port: 1970
    resources:
      memory: 512Mi

Managing sidecars

The canasta sidecar subcommands operate on config/sidecars.yaml. Identify the instance with -i/--id (or -p/--path) as with other commands.

add — declare sidecar(s) from a YAML file (--file is required). The file uses the agnostic schema and may contain a single mapping, a list, or a sidecars: list. The definitions are merged into config/sidecars.yaml.

canasta sidecar add -i mywiki --file sidecars.yaml

list — list the declared sidecars with their image (or build context) and ports.

canasta sidecar list -i mywiki

remove — remove one sidecar declaration by name. This removes the service on the next restart; it does not touch any wiki-side configuration that referenced it.

canasta sidecar remove -i mywiki --name cache

migrate — translate sidecar services already defined in a legacy docker-compose.override.yml into the agnostic schema. It moves them: the services are written to config/sidecars.yaml and removed from the override file (a left-behind override entry would shadow the migrated sidecar). Use --dry-run to preview the translation. A named Docker volume becomes a persistent volume with an assumed 1Gi size.

canasta sidecar migrate -i mywiki --dry-run
canasta sidecar migrate -i mywiki

For richer sidecars (mounted config files, dependencies, healthchecks) you can also edit config/sidecars.yaml directly. In every case, run canasta restart afterward to apply.

Reaching a sidecar from the wiki

A sidecar is reachable on the instance network by its name as the hostname, on the ports it declares — e.g. the cache sidecar above is cache:6379. Configure MediaWiki to use it the usual way, in the per-wiki or global settings (see Help:General concepts); for example, point $wgObjectCaches at cache:6379. The sidecar declaration provisions the service; wiring the wiki to it is ordinary MediaWiki configuration.

The web environment bridge

A sidecar and the wiki often need to share a value — most commonly a secret. If a sidecar's env block references a variable with ${VAR} and that same VAR is set in the instance's .env, Canasta bridges it to the web tier: it writes a small PHP fragment (config/settings/global/00-canasta-sidecar-env.php) that does putenv() for that variable, so MediaWiki's getenv('VAR') returns the same value the sidecar received. Variables that are referenced but not present in .env are left alone (the web app falls back to its own default). The bridge is regenerated on each render and removed when no sidecar references a bridged variable.

Building sidecar images

Instead of pulling a published image, a sidecar can be built from a local build context with build:. Image delivery differs by orchestrator, but the declaration is the same:

Docker Compose — the image is built locally on the host.
Kubernetes — the image is built and pushed to the cluster's in-cluster registry, so every node (including remote workers) can pull it. This is the same registry mechanism used by canasta create --build-from on Kubernetes.

GitOps

config/sidecars.yaml and any files: it references are part of the instance's configuration, so on a GitOps-managed instance they are version-controlled and travel with the rest of the config. Stage them like any other config change (canasta gitops add config/sidecars.yaml ...) before pushing.