Troubleshooting¶

Check health¶

strawly status

This shows the versions, whether the backend answers, and the state of every container. With several instances, add -i <name>.

Settings > About in Strawly shows the same versions, and whether each module is compatible.

Read the logs¶

strawly logs                       # all services
strawly logs backend               # one service
strawly logs optimizations-azure

Press Ctrl+C to stop following.

Common issues¶

The installer says Docker is not running¶

On macOS and Windows, start Docker Desktop and wait until it reports that it is running. On Linux, start the service:

sudo systemctl start docker

The HTTPS certificate is not issued¶

Symptom: the browser shows a certificate warning, or the site does not load over HTTPS.

1. Check that the domain points to the server: dig +short strawly.example.com must print the server's public IP.
2. Check that ports 80 and 443 are open to the internet in the server's firewall or network security group. Let's Encrypt connects on port 80.

3. Read the edge proxy logs:

   docker compose -p strawly-edge logs caddy
   

A module shows as paused¶

Symptom: a banner says a module is paused, or Settings > About marks it as not compatible.

The module and the core run versions that do not work together. The banner names both versions and what to upgrade. In most cases:

strawly upgrade

The page says the frontend does not match the backend¶

The frontend and backend must run the same version. This happens when .env was edited by hand with different versions, or an image was replaced manually. Run strawly upgrade, or set one STRAWLY_VERSION and run strawly apply.

Sign-in does not stick on a local network address¶

Symptom: you sign in at http://<server-ip>:<port> and land back on the sign-in page.

A proxy in front of Strawly is probably sending X-Forwarded-Proto: https for a plain HTTP connection, so the browser drops the login cookie. Remove that header for HTTP, or serve the address over HTTPS.

Port already in use¶

Symptom: bind: address already in use when starting.

Another program took the instance's port after Strawly was installed. Move the instance to a free port with strawly set-port <port>. It checks that the new port is free first.

Migrations failing¶

Symptom: the backend does not start, and strawly status shows migrations exited with an error.

strawly logs migrations

If you moved to an older version without restoring its backup, the database is newer than that version expects. Go back with strawly rollback, or upgrade again.

Start over with an empty database¶

strawly backup
strawly compose down -v
strawly apply

down -v deletes the instance's volumes, including the database. On the next start, Strawly creates the database again with the admin account from .env. Set ADMIN_PASSWORD in .env again before strawly apply, because the installer removed it.