Enviroment Variables

Local Development

Copy .env.example to .env.local and fill in the values you need:

cp .env.example .env.local

Most pages need Supabase (NEXT_PUBLIC_SUPABASE_URL and NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY). Everything else is only needed by the feature that uses it, and most variables fall back to the production value when they aren't set.

Build-time and runtime variables

The site has two kinds of environment variable, and they're set in different places:

• Build-time: NEXT_PUBLIC_* variables read in browser code. next build writes their values into the JavaScript bundle, so they're fixed when CI builds the Docker image. Changing the .env on the server has no effect on them.
• Runtime: variables read by server code (the API routes) while the container runs. They come from /opt/apps/abair_website/.env on services-user, which is written from Vaultwarden.

The main site (abair.ie) and preview (preview.abair.ie) use the same build-time values and the same .env.

Build-time variables

Variable	Set in production	Default	Used for
NEXT_PUBLIC_SUPABASE_URL	GitHub variable	None	Supabase project URL
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY	GitHub variable	None	Supabase publishable key
NEXT_PUBLIC_ABAIR_API_URL	No, uses the default	https://api.abair.ie/v4	API gateway, for speech synthesis and the daily allowance
NEXT_PUBLIC_ABAIR_ANON_KEY	No, uses the default	anon_abair	Identifies the site to the gateway for visitors who aren't signed in
NEXT_PUBLIC_ABAIR_AUTH_URL	No, uses the default	https://auth.abair.ie	Central auth: sign-in, sign-out, account links and silent sign-in
NEXT_PUBLIC_WEBREADER_URL	No, uses the default	https://webreader.abair.ie	Where the Web Reader script loads from

Setting a build-time variable in production

These values aren't secret, so they don't go in Vaultwarden. Make three changes:

1. Dockerfile: in the builder stage, add ARG NAME and ENV NAME=$NAME before RUN npm run build.
2. .github/workflows/cd.yml: add NAME=${{ vars.NAME }} to the build-args of the build step.
3. GitHub: add NAME as a variable in the repository's prod environment (Settings → Environments → prod).

The value takes effect on the next push to main or preview. If the code already has a default, you only need this when production should use a different value.

Runtime variables

These are set in the abair_website .env Secure Note in Vaultwarden, in the abair_website collection.

Variable	Used for
OPENAI_API_KEY	Speech-to-speech replies (/api/s2s)
SMTP_HOST	Mail server for the contact form. Defaults to smtp.mailbox.org
MAILBOX_SMTP_USER	mailbox.org login that sends from info@abair.ie and no-reply@abair.ie. Defaults to abair@mailbox.org
MAILBOX_SMTP_PASSWORD	Password for that login
MAILING_CONFIRM_SECRET	Signs mailing-list confirmation links. Supabase holds the same value in private.abair_secrets (mailing_confirm_secret)
REDDIT_CLIENT_ID, REDDIT_CLIENT_SECRET, REDDIT_USER_AGENT	Optional. Reddit posts (/api/reddit)

NEXT_PUBLIC_HOST_URL is an exception. Server code reads it at runtime as the base for links in emails, and it differs between the two sites, so it's set per container in the compose file (https://abair.ie and https://preview.abair.ie) rather than in .env.

Changing a runtime variable

1. Edit the abair_website .env note in Vaultwarden.

2. From infrastructure-automation, run:

   eval "$(make unlock-bw)"
   make deploy-services-user-apps

   This writes the new .env to the server and runs docker compose up -d. Pushing to main or preview doesn't update .env.

For a new runtime variable, also note it in ansible/hetzner-main/services-user-apps/abair_website/docker-compose.yml through an infrastructure-automation PR. Get it live on the server before merging the code that needs it to main: pushing to main deploys to production straight away.

See Adding an App to Services User or Staff for how the .env notes work.