Common tasks

From Canasta Wiki

This page covers common configuration tasks for managing Canasta instances, including configuring logos, permissions, and deployment options.

Configuration commands

Canasta has four commands for managing instance configuration:

  • canasta config get [KEY] — show the value of a configuration key, or all known keys if KEY is omitted.
  • canasta config set KEY=VALUE — change a configuration value. The set of recognized keys is enforced; use --force to set keys outside the known list.
  • canasta config unset KEY — remove a setting (reverts to default).
  • canasta config regenerate — re-render derived config files (Caddyfile, wikis.yaml, etc.) from current sources. Use after manually editing source files or when troubleshooting drift.

Configuration is stored in the instance's .env file (Compose) or the corresponding Kubernetes Secret/ConfigMap. The four commands above keep those, the in-instance derived files, and the rendered Caddyfile consistent. See CLI:canasta config for the full reference.

Inspecting an instance

To check whether an instance is running and see its containers, volumes, ingress, and (on Kubernetes) TLS certificate state in one place: 

canasta status --id mywiki

Works for both Docker Compose and Kubernetes — no need to remember docker compose ps vs. kubectl get pods,pvc,ingress,certificate -n canasta-mywiki. Add --host <name> when canasta runs on a different machine than the instance.

For Kubernetes instances under gitops management, list Argo CD Applications and their sync/health state: 

canasta argocd apps --host node1

Storage classes available on the cluster (and the canasta-configured default for new instances): 

canasta storage list --host node1

The full set of inspection-style commands lives under CLI:canasta — see also CLI:canasta list for the registry-wide table, CLI:canasta argocd for the Argo CD command group, and CLI:canasta gitops status for git-side state.

Default settings

Aggressive bots routinely target new wikis as soon as they appear on the internet. It is a better security posture to start with a closed wiki, ensure all appropriate access controls and content are in place, and then make a deliberate choice about when and how to open it up.

New Canasta instances include a config/settings/global/DefaultSettings.php file that makes all wikis private by default. The file contains: 

<?php
$wgGroupPermissions['*']['read'] = false;
$wgGroupPermissions['*']['edit'] = false;
$wgGroupPermissions['*']['createaccount'] = false;

This prevents anonymous users from reading, editing, or creating accounts on any wiki in the instance.

Making a wiki public

The three permissions control different levels of access for anonymous (logged-out) users:

  • read — view pages. Set to true to make the wiki publicly readable.
  • edit — edit pages. Most public wikis leave this false so that only registered users can make changes.
  • createaccount — register new accounts. Set to true if you want anyone to be able to sign up. Leave false if administrators should control who gets an account.

To make all wikis publicly readable, edit config/settings/global/DefaultSettings.php and change the permissions you want to allow. For example, a common configuration for a public wiki that requires login to edit: 

<?php
$wgGroupPermissions['*']['read'] = true;
$wgGroupPermissions['*']['edit'] = false;
$wgGroupPermissions['*']['createaccount'] = true;

To delete the file entirely is equivalent to setting all three to true (MediaWiki's built-in defaults).

To make a specific wiki public while keeping others private, create a per-wiki settings file: 

<?php
// config/settings/wikis/{wiki-id}/Permissions.php
$wgGroupPermissions['*']['read'] = true;
$wgGroupPermissions['*']['createaccount'] = true;

Per-wiki settings are loaded after global settings, so they override the defaults for that wiki only. Permissions not listed in the per-wiki file keep the global value (in this example, edit remains false).

See the MediaWiki documentation for the full list of available permissions.

Configuring logos and favicons

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 and favicon 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
cp /path/to/favicon.ico public_assets/{wiki-id}/favicon.ico

The URL path used to reference these files depends on each wiki's url in wikis.yaml:

  • If the wiki's url has no path component (e.g. wiki.example.com), reference assets at /public_assets/....
  • If the wiki's url has a path component (e.g. wiki.example.com/docs), include that path: /docs/public_assets/....
  • With very short URLs enabled (CANASTA_ENABLE_VERY_SHORT_URLS=true): the very-short-URL article rewrite intercepts root-level /public_assets/... requests, so reference assets through the script path with the explicit wiki ID instead — /w/public_assets/{wiki-id}/logo.png (and likewise for the favicon).

For each wiki, configure logo and favicon in a per-wiki settings file. Example for a wiki with no URL path: 

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

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

For a wiki whose url is wiki.example.com/docs: 

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

Apache routes /[<path>/]public_assets/... requests to the correct wiki's filesystem subdirectory based on the request's hostname and (when present) URL 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


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 instance, 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 instance: 

canasta config set CADDY_AUTO_HTTPS=off

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

canasta config unset CADDY_AUTO_HTTPS

Changing the domain name

The domain name for each wiki is stored in config/wikis.yaml in its url field. Each wiki has a domain name (possibly a subdomain) and an optional path component. Examples:

The .env file 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 instance as listed in the config/wikis.yaml file. In a wiki farm, additional wikis may use the same domain (path-based) or different domains (a completely different domain or subdomain with an optional path), and their URLs are managed entirely in wikis.yaml.

GitOps-managed instances: if your instance is managed with gitops, config/wikis.yaml and .env are rendered files and editing them by hand is not durable. See GitOps instances below.

Single wiki or path-based farm

To change the domain of the primary wiki and any other wikis using that domain, change it with a single command: 

canasta config set MW_SITE_FQDN=newdomain.example.com

MW_SITE_FQDN is the bare domain (no scheme). The scheme (http:// or https://) is preserved from the existing MW_SITE_SERVER. To switch schemes at the same time, run a follow-up canasta config set MW_SITE_SERVER=https://newdomain.example.com afterward.

This cascades automatically:

  • Updates MW_SITE_FQDN in .env and rewrites MW_SITE_SERVER with the new domain (preserving the scheme)
  • Rewrites the url field in config/wikis.yaml only for wikis whose current host matches the old MW_SITE_FQDN — wikis on different domains (e.g. subdomain-based farm members) are not touched
  • Regenerates the Caddyfile from the updated wikis.yaml and restarts the instance

If you also need to change a path-based wiki's path component (e.g. /docs → /knowledge), edit config/wikis.yaml directly — the cascade above only rewrites the domain portion — then regenerate the configuration and restart: 

canasta config regenerate
canasta restart

Domain-based farm

When wikis use different domains or subdomains, you only need to change MW_SITE_FQDN (as above) if the primary wiki's domain is changing.

To change a non-primary wiki's domain, edit its url in config/wikis.yaml, then regenerate the Caddyfile and restart: 

canasta config regenerate
canasta restart

Note: canasta restart on its own does not regenerate the Caddyfile. A hand-edited domain in wikis.yaml will not be served by Caddy until you run canasta config regenerate, even though MediaWiki itself will already recognize the entry.

GitOps instances

On a gitops-managed instance, config/wikis.yaml and .env are rendered files. The source of truth is hosts/<host>/vars.yaml together with the *.template files, and both canasta config regenerate and canasta gitops pull re-render the rendered files from them. Editing config/wikis.yaml or .env by hand is therefore not durable — the next regenerate or pull reverts the change.

Edit the values in hosts/<host>/vars.yaml instead, then regenerate, restart, and push:

  • Primary wiki domain: set mw_site_fqdn and mw_site_server.
  • Any wiki's domain: set that wiki's wiki_url_<id>.
# after editing hosts/<host>/vars.yaml
canasta config regenerate
canasta restart
canasta gitops push

For the primary wiki you can instead use canasta config set MW_SITE_FQDN=newdomain.example.com, which records the change in hosts/<host>/vars.yaml (as well as the rendered files) for you; follow it with canasta gitops push.

Port changes

Listening ports are a Docker Compose concept: the port is set in .env and mapped by the Compose stack. On Kubernetes the Ingress always serves on ports 80 and 443 and there is no per-instance port setting, so canasta config set HTTP_PORT/HTTPS_PORT is rejected on a Kubernetes instance — expose a different external port at the load balancer or Ingress controller instead.

On Compose, changing the port is a separate operation from changing the domain, and unlike the domain it is instance-wide: every wiki in the instance shares the same listening port. There is no per-wiki port — a non-primary wiki cannot listen on a different port than the primary wiki. To change the port for the whole instance, run: 

canasta config set HTTPS_PORT=<port>

This cascades automatically, appending the new port to the URLs of all wikis in config/wikis.yaml as well as to MW_SITE_SERVER and MW_SITE_FQDN (which take their domain from the primary wiki). Setting the port back to the scheme default (443 for HTTPS, 80 for HTTP) removes the suffix again. (Set HTTP_PORT instead if the instance runs with CADDY_AUTO_HTTPS=off, in which case the plain-HTTP port is the active one.) See Running on non-standard ports.

Because the domain and port cascades are independent, changing both at once means running both commands — set the domain (MW_SITE_FQDN, or a non-primary wiki's url in config/wikis.yaml) and set the port (HTTPS_PORT); neither replaces the other.

On a gitops-managed instance the rendered config/wikis.yaml and .env are rewritten the same way, but because those files are regenerated the durable change is recorded to hosts/<host>/vars.yaml: https_port (the raw port number), the derived mw_site_fqdn/mw_site_server, and a wiki_url_<id> entry for every wiki — each carrying the new port suffix. Without this the next config regenerate or gitops pull would revert the port. Follow the change with canasta gitops push.

Redirecting legacy URL paths

When migrating an existing wiki into Canasta, the URL shape your readers and external links know may not match what Canasta produces. For example, a wiki that ran at the document root ($wgScriptPath = "") served pages at https://example.com/index.php?title=Page_Name; in Canasta, those same pages live at https://example.com/wiki/Page_Name. External links and bookmarks to the old URLs will return 404 unless you redirect them.

Caddy handles these redirects at the reverse proxy layer. Add a redirect rule to config/Caddyfile.site that matches the old URL pattern and rewrites it to the new one. (See Caddyfile, Caddyfile.site, and Caddyfile.global for how Caddyfile.site fits into the stack — it takes the place of .htaccess in an Apache-based install.)

Example: redirect /index.php?title=X to /wiki/X

If the wiki previously served pages at /index.php?title=Page_Name (no /w/ prefix, no path-rewrite layer), add this to config/Caddyfile.site: 

@legacyTitle {
    path /index.php
    query title=*
}
redir @legacyTitle /wiki/{http.request.uri.query.title} 301

After saving the file, restart the instance: 

canasta restart

https://example.com/index.php?title=My_Page now issues a 301 redirect to https://example.com/wiki/My_Page, preserving the link target.

Notes

  • Use a 301 (permanent) redirect for URLs that are genuinely retiring; use 302 (temporary) if you might revert.
  • Caddy's matchers and redir directive are documented at caddyserver.com/docs/caddyfile/directives/redir. Most legacy URL patterns are expressible with one or two matchers and a redir.
  • If migrating an entire URL scheme (not just a few paths), be cautious about wildcard fallbacks at the end of the site block — they can mask legitimate 404s.

Very short URLs

By default a Canasta wiki serves pages at /wiki/Page_Name — the standard "short URL" pattern documented in Manual:Short URL on mediawiki.org. Canasta also supports an optional "very short URL" mode that drops the /wiki/ prefix, so pages live directly at /Page_Name.

Enable it with: 

canasta config set CANASTA_ENABLE_VERY_SHORT_URLS=true

This restarts the instance and reconfigures Caddy and MediaWiki so the wiki "owns" the entire URL space at the root.

Constraints

Because very short URLs put pages at the root path, they conflict with anything else that uses root paths on the same hostname. canasta config set validates these constraints before enabling and refuses with an actionable error if any are violated:

  • Each wiki must be on a unique hostname. Path-based wiki farm entries (e.g. example.com/docs in wikis.yaml) are not allowed when very short URLs are on. Each wiki's url must be a hostname only, with no path component.
  • CANASTA_ENABLE_WIKI_DIRECTORY must be off. The wiki directory is served at /wikis, which would collide with a page titled Wikis under root-relative URLs.

To switch a multi-wiki instance from path-based to hostname-based wikis before enabling very short URLs, see Changing the domain name above.

Disabling

canasta config set CANASTA_ENABLE_VERY_SHORT_URLS=false

After disabling, page URLs revert to the standard /wiki/Page_Name form. Existing page titles are unaffected — only the URL routing changes.

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