Use the Nix development shell

Use this route if you already work with Nix. Start from the checkout in Set up a local development environment. Install Nix using its official installation instructions if needed.

1. Enter the supplied shell

From the repository root:

nix-shell

Wait for dependencies to finish downloading or building. The checked-in shell.nix selects erlang_28 and includes PostgreSQL tools and the platform's file watcher. Keep this shell open for all build and Zotonic commands.

Check the runtime:

erl -noshell -eval 'io:format("~s~n", [erlang:system_info(otp_release)]), halt().'

Expect 28.

2. Start a local database

The shell supplies PostgreSQL programs; it does not start a database server. If you already have a local server, follow Prepare local PostgreSQL.

Otherwise, create a new development cluster in the checkout, as your normal user:

initdb -D .local-postgres --auth-local=peer --auth-host=scram-sha-256
pg_ctl -D .local-postgres -l .local-postgres/server.log -o "-h localhost -p 5432 -k $(pwd)/.local-postgres" start

Add .local-postgres/ to .git/info/exclude so database files stay out of Git. Use an empty directory for initdb. If port 5432 is already occupied, use the existing local server or configure a different port throughout.

Local peer authentication uses your operating-system username. Open psql -h "$(pwd)/.local-postgres" postgres as that same user and follow the SQL in Prepare local PostgreSQL.

3. Build and try a site

Follow Build and start Zotonic and Create your first site inside the Nix shell. If you open another terminal for Zotonic commands, enter nix-shell there too.

When finished, stop Zotonic with bin/zotonic stop. If you started the cluster above, stop it with pg_ctl -D .local-postgres stop before leaving the shell. Keep the directory to reuse its data next time.