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 instances on the same server — the approach depends on whether you are creating a new instance 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 instances 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 instance

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 instance

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 instances on the same machine

Each Docker Compose instance on the same host must use unique ports.

# Default ports (80/443)
canasta create -i production -w mainwiki -n localhost
# Custom ports
canasta create -i staging -w testwiki -n localhost:8443 -e custom.env

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

For Kubernetes, multiple instances on the same cluster typically share the standard ports (80/443) and are differentiated by hostname via the cluster's ingress controller, rather than by port. See Ingress and TLS.