Best practices

This page covers security considerations, operational best practices, and deployment guidance for Canasta instances. For foundational concepts and architecture, see General concepts.

Security

Password storage

Admin passwords are stored in plaintext files at config/admin-password_{wikiid}
Database passwords are stored in plaintext in the .env file
Restrict access to the instance directory using file permissions:

# Owner can read/write/traverse; group (www-data) can read/traverse; others have no access
chmod 750 /path/to/instance
chmod 640 /path/to/instance/.env
chmod 640 /path/to/instance/config/admin-password_*

If using GitOps, ensure that files containing passwords (.env, config/admin-password_*) are excluded from version control. The default .gitignore created by canasta gitops init already excludes these files.
Avoid passing passwords directly on the command line — they may appear in shell history and process listings. Use environment variables instead:

canasta create -i myinstance -w main --rootdbpass "$ROOT_DB_PASS"

Docker access

Running Canasta CLI commands does not require sudo. On Linux, your user must be in the docker and web server groups. See the Installation guide for setup instructions and the Troubleshooting page if you encounter permission errors.

Network exposure

By default, Canasta exposes ports for HTTP/HTTPS traffic
Caddy handles SSL/TLS termination automatically
To customize Caddy behavior (headers, redirects, etc.), edit config/Caddyfile.site — do not edit config/Caddyfile directly as it is regenerated when wikis change
Consider adding security headers in config/Caddyfile.site:

header X-Frame-Options "SAMEORIGIN"
header X-Content-Type-Options "nosniff"
header Referrer-Policy "strict-origin-when-cross-origin"

Review your docker-compose.override.yml if you need to customize port bindings or network settings

Operations

Backups

Set up regular backups using canasta backup
Always take a backup before running canasta upgrade
For production wikis, schedule automated backups using canasta backup schedule set so you have recent restore points
Store backup passwords securely and separately from your server
Test your backup restoration process periodically — an untested backup is not a backup
See the Backup guide for full details on creating, restoring, and managing backups

GitOps

For production wikis, consider using GitOps to track your instance configuration in a Git repository. This provides version history for settings changes, makes it easy to replicate an instance, and enables collaborative configuration management. See the GitOps guide for setup instructions.

Upgrading

Check release notes before upgrading — some releases may require manual steps
Always back up before upgrading
For production wikis, test upgrades on a staging instance first (see Common tasks: Running on non-standard ports for running multiple instances)
See the Upgrading guide for pre-upgrade steps and the full upgrade process

Managing multiple instances

Use descriptive instance IDs that indicate the purpose (e.g., company-wiki, docs-internal)
Keep a record of which wikis are in each instance if using wiki farms
Use canasta list regularly to review your instances

Wiki ID naming rules

Wiki IDs may contain only alphanumeric characters and underscores. Hyphens (-) are not allowed (they are allowed in instance IDs, but not wiki IDs). The following names are reserved and cannot be used: settings, images, w, wiki.

Valid examples: mywiki, wiki_1, MyWiki2024, docs

Invalid examples: my-wiki, my wiki, wiki!, settings

Note: Instance IDs (the -i flag) have different rules — they allow hyphens and underscores, must start and end with an alphanumeric character, and have no reserved names.