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

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. 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 instance. 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, change the server URL with a single command: 

canasta config set MW_SITE_SERVER=https://newdomain.example.com

This cascades automatically:

  • Updates MW_SITE_SERVER and MW_SITE_FQDN in .env
  • Rewrites the url field in config/wikis.yaml only for wikis whose current host matches the old MW_SITE_FQDN — wikis on different domains (subdomain-based farms) are not touched
  • Triggers a restart, which regenerates the Caddyfile from the updated wikis.yaml

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 run canasta restart.

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

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.

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

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

If the wiki previously served pages at /w/index.php?title=Page_Name (the conventional MediaWiki layout with $wgScriptPath = "/w"), use this instead: 

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

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=646"
Powered by MediaWiki
Powered by Canasta