Install and site access

Run the three checks under Start here first. They tell you which part is broken.

Install and startupCopy Anchor Link

The app stops at once and the log says DATABASE_URL is not setCopy Anchor Link

The service started without its settings file. The full message is DATABASE_URL is not set (for example postgres://imbox:password@localhost:5432/inbox).

• On a server, check that /etc/imbox/imbox.env exists and has a DATABASE_URL= line. The setup script writes it. If you moved or deleted it, imbox.env.example in the deploy folder shows the shape.
• With Docker, DATABASE_URL is built from POSTGRES_PASSWORD in .env. Check that .env sits next to docker-compose.yml.

Docker Compose stops with set POSTGRES_PASSWORD in .envCopy Anchor Link

Compose refuses to start when a required value is empty. It names the missing one: POSTGRES_PASSWORD, APP_URL, or SESSION_SECRET (openssl rand -hex 32). Fill it in .env, then run docker compose up -d again.

The log shows postgres pool: errorsCopy Anchor Link

The app cannot reach the database.

• Server: sudo systemctl status postgresql. If it is stopped, sudo systemctl start postgresql. Check that the password in DATABASE_URL is the one the setup script created for the imbox role.
• Docker: docker compose ps should show the db container as healthy. If it is restarting, docker compose logs db says why. A changed POSTGRES_PASSWORD does not change a database that already exists. Either put the old password back or, if you have nothing to keep, remove the volume with docker compose down -v.

The setup script stops partwayCopy Anchor Link

It is safe to run again. It skips what is already installed and keeps an existing /etc/imbox/imbox.env. Read the last lines it printed for the step that failed. The usual causes are no network from the server, or a system older than Debian 12 or Ubuntu 22.04.

imbox-activate prints New release did not become healthyCopy Anchor Link

The new release did not answer healthz within about a minute, so the script put the previous release back and printed the last 40 log lines. Read them. The cause is almost always one of the entries above. Your site stays on the old release while you fix it.

After the setup script, the site shows 502 or nothingCopy Anchor Link

The setup script installs the services but does not put the app on the server. Do step 2 of Install, then check healthz again.

The site does not openCopy Anchor Link

The browser warns about the certificate, or the connection failsCopy Anchor Link

Caddy gets a certificate on its own, but only when the domain already reaches the server and port 80 is open.

1. dig +short imbox.example.com must print your server's IP address. If it prints nothing or another address, fix the DNS record and wait for it to spread.
2. Ports 80 and 443 must be open in the server's firewall and in your cloud provider's firewall. The setup script opens them on the machine, not at the provider.
3. Read what Caddy says: sudo journalctl -u caddy -n 50 --no-pager. A line about a failed challenge names the reason.

If you put a proxy such as Cloudflare in front, set its encryption mode to "Full (strict)", or you get redirect loops.

Caddy answers 502 Bad GatewayCopy Anchor Link

Caddy is up but the app is not. Run the three checks under Start here.

Live updates never arrive, and new mail shows only after a reloadCopy Anchor Link

A proxy in front of the app is holding the live stream back. Turn off response buffering for /api/events. With Caddy add flush_interval -1 inside reverse_proxy, as in Install. With nginx use proxy_buffering off; for that path.

Actions fail with "This request did not come from the app"Copy Anchor Link

You can read mail, but sending, moving or saving fails with This request did not come from the app. (cross_site_request, status 403).

imbox refuses any change request whose origin is not its own address. The address it expects is the host in APP_URL, or the host the request arrived on. A proxy that rewrites the host breaks the second one.

1. Open /etc/imbox/imbox.env (or .env for Docker). APP_URL must be exactly the address in your browser's address bar, with https:// and no trailing path: APP_URL=https://imbox.example.com.
2. Restart: sudo systemctl restart inbox, or docker compose up -d.
3. If you use a proxy other than Caddy, pass the original host on to the app (nginx: proxy_set_header Host $host;).