Common tasks

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

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

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

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

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.