A site does not start

Run bin/zotonic status to distinguish an unavailable node from a stopped or failing site. Inspect the relevant startup log before repeatedly restarting it.

For a site failure, check configuration parsing, database access, required applications, and module initialization. Use siteconfigfiles to confirm which configuration files were selected. Do not paste credentials from configuration output into an issue.

Fix the first reported cause, start the site again, and verify an HTTP response. Later errors may be consequences of the first startup failure.

Check or change a site database connection

Access needed: Database and server configuration access.

1. Identify the site's effective database host, port, database name, role, and schema. Do not print the password into a shared report.
2. Test connectivity from the same host or container that runs Zotonic. A successful connection from your laptop may follow a different route.
3. Check authentication and the role's access to the intended database and schema.
4. Make a required connection change in acceptance first, at the owning configuration layer.
5. Restart or reload according to the deployment procedure and check startup logs.
6. Verify an existing page and a small write using the intended site account. Confirm that you did not connect to an empty or wrong environment's database.

A schema separates site tables within a database; it is not a substitute for environment isolation. Do not grant superuser rights to bypass a permissions error. For a fresh local development database, use the developer setup task instead of adapting production credentials.

Local socket connections

For PostgreSQL on the same host, set dbhost to socket (atom, string, or binary) to use /run/postgresql, or set it to an absolute socket directory. dbport selects .s.PGSQL.<port>, normally .s.PGSQL.5432. This mode does not fall back to TCP.

Check SHOW unix_socket_directories; in PostgreSQL and test with psql -h /run/postgresql -p 5432 -U ROLE -d DATABASE as the Zotonic service user. Socket connections use local rules in pg_hba.conf; TCP connections use host rules. Match the intended password or peer-authentication policy. Keep the socket directory writable only by trusted users. For containers, verify the mount and permissions inside the container.

Configure hostnames and HTTPS

Access needed: DNS and server configuration access.

1. Decide the canonical hostname and required aliases. Make DNS point to the intended server or reverse proxy.
2. Set the matching site hostname and aliases, and check the externally visible HTTP/HTTPS ports.
3. Choose where TLS terminates: Zotonic or a reverse proxy. Install certificates through that component's supported mechanism.
4. If using a proxy, forward the expected host and protocol information and support WebSocket connections. Keep direct backend access consistent with the deployment's access policy.
5. Test the canonical URL and each alias, redirects, certificate hostname and chain, admin login, and a live browser interaction.
6. Check certificate renewal and monitor expiry before it becomes an outage.

A working DNS record does not select the correct Zotonic site unless the hostname matches its configuration. A certificate working in your own browser is not proof that public clients trust it.

For a local first run, use the developer setup instructions. Production certificates, public redirects, and proxy settings need the actual deployment's reviewed configuration.