Help:Running on non-standard ports

By default, Canasta uses ports 80 (HTTP) and 443 (HTTPS). To use different ports — for example, to run multiple Canasta installations on the same server — the approach depends on whether you are creating a new installation or changing an existing one.

TLS certificates and non-standard ports

When Canasta is configured with a real domain name, Caddy automatically obtains a TLS certificate from Let's Encrypt. This uses the ACME HTTP-01 challenge, which requires Let's Encrypt to connect to port 80 on your server. If you set HTTP_PORT to a non-standard value, the challenge will fail because Let's Encrypt cannot reach Caddy on port 80.

Non-standard ports are therefore intended for local development and testing (e.g., localhost:8443), not for production deployments with automatic TLS.

If you need to run multiple Canasta installations with TLS on the same server, place a shared reverse proxy (such as Caddy or nginx) in front of all instances. The reverse proxy holds ports 80/443, obtains the certificates, and forwards traffic to each Canasta instance on its internal ports. In this setup, each Canasta instance should set CADDY_AUTO_HTTPS=off in its .env file so its built-in Caddy does not attempt its own ACME challenges.

New installation

Pass an env file with port settings to canasta create. Create a file called custom.env:

HTTP_PORT=8080
HTTPS_PORT=8443

canasta create -i staging -w testwiki -n localhost:8443 -e custom.env

Existing installation

Use canasta config set. Multiple settings can be changed in a single command. The HTTPS_PORT side effect automatically updates config/wikis.yaml URLs, MW_SITE_SERVER, and MW_SITE_FQDN to match:

canasta config set HTTP_PORT=8080 HTTPS_PORT=8443

To revert to the default ports (80/443), remove the overrides:

canasta config unset HTTP_PORT HTTPS_PORT

Multiple installations on the same machine

Each installation must use unique ports. This applies to both Docker Compose and Kubernetes (--create-cluster) installations — they can be mixed freely.

# Docker Compose installation on default ports (80/443)
canasta create -i production -w mainwiki -n localhost
# Docker Compose installation on custom ports
canasta create -i staging -w testwiki -n localhost:8443 -e custom.env

# Local Kubernetes installation on different custom ports
canasta create -o k8s --create-cluster -i dev-k8s -w devwiki -n localhost:9443 -e another.env

Access them at https://localhost, https://localhost:8443, and https://localhost:9443.