Environment Variables

Environment variables let you configure Primo for different deployment environments. These are particularly useful for Docker deployments and automated setup.

Legacy PALA_* variable names are still accepted as fallbacks, but new deployments should use the PRIMO_* names documented below.

Initial Setup Variables

These variables only take effect on first startup when initializing a new instance:

`PRIMO_SUPERUSER_EMAIL`

Creates an initial superuser account (admin) with full access.

Type: String (email address)
Required: No
Default: None
When to use: Automated deployments, skipping manual setup

Example:

PRIMO_SUPERUSER_EMAIL=admin@example.com

`PRIMO_SUPERUSER_PASSWORD`

Password for the initial superuser account.

Type: String
Required: Only if PRIMO_SUPERUSER_EMAIL is set
Default: None
Minimum: 8 characters

Example:

PRIMO_SUPERUSER_PASSWORD=secure-password-123

If both PRIMO_SUPERUSER_EMAIL and PRIMO_SUPERUSER_PASSWORD are set, the setup screen will be skipped and you’ll go straight to the sign-in page.

`PRIMO_USER_EMAIL`

Creates an initial regular user account.

Type: String (email address)
Required: No
Default: None
When to use: Pre-populate with a content editor account

Example:

PRIMO_USER_EMAIL=editor@example.com

`PRIMO_USER_PASSWORD`

Password for the initial regular user account.

Type: String
Required: Only if PRIMO_USER_EMAIL is set
Default: None
Minimum: 8 characters

Example:

PRIMO_USER_PASSWORD=editor-password-123

`PRIMO_APP_URL`

Sets the base URL for the application. Used for generating links in emails and backend processes.

Type: String (URL)
Required: No
Default: Auto-detected from request
When to use: Email notifications, API callbacks

Example:

PRIMO_APP_URL=https://cms.example.com

Custom Domain Variables

These control how sites get a public address: an automatic subdomain on creation, and connecting a site’s own custom domain.

`PRIMO_BASE_DOMAIN`

A wildcard base domain under which new sites get an automatic, live subdomain (<site-slug>.<base-domain>) the moment they’re created. Without it, new sites start unassigned (editable but not publicly served) until a domain is connected.

Type: String (domain)
Required: No
Default: Empty (new sites start unassigned)
When to use: Multi-site instances where every site should be reachable immediately without manual DNS.

Setting this variable only tells Primo which subdomains to assign. For those subdomains to actually resolve and serve over HTTPS, you must separately point a wildcard DNS record (*.<base-domain>) at this server and provision a matching wildcard TLS certificate. Primo does not create the DNS record or the certificate.

Example:

PRIMO_BASE_DOMAIN=sites.example.com
# A site named "Acme Co" becomes https://acme-co.sites.example.com

`PRIMO_DOMAIN_PROVIDER`

Selects how connecting a site’s own custom domain works. manual (the default) shows the DNS records to add and leaves routing/TLS to your reverse proxy; railway attaches the domain through Railway’s API and reports certificate status back to the editor.

Type: String (manual | railway)
Required: No
Default: manual
When to use: Set to railway when the instance runs on Railway and you want custom domains attached automatically.

Example:

PRIMO_DOMAIN_PROVIDER=railway

`PRIMO_RAILWAY_TOKEN`

A Railway project access token scoped to the same environment as Primo, used only when PRIMO_DOMAIN_PROVIDER is railway. Create it in the Railway dashboard under the project’s Settings → Tokens (environment-scoped within the project; use the least-privileged token). A token for a different environment causes domain provisioning to fail. The project/environment/service IDs Railway injects automatically (RAILWAY_PROJECT_ID, etc.) supply the rest.

Type: String (token)
Required: Only when PRIMO_DOMAIN_PROVIDER=railway
Default: Empty

Example:

PRIMO_RAILWAY_TOKEN=your-railway-project-token

Common Configurations

Development Setup

# No environment variables needed
# Just run: docker-compose up

The setup screen will guide you through creating your first account.

Production with Manual Setup

PRIMO_APP_URL=https://cms.example.com

Access the setup screen to create your admin account manually.

Production with Automated Setup

PRIMO_APP_URL=https://cms.example.com
PRIMO_SUPERUSER_EMAIL=admin@example.com
PRIMO_SUPERUSER_PASSWORD=strong-random-password
PRIMO_USER_EMAIL=editor@example.com
PRIMO_USER_PASSWORD=another-strong-password

No setup screen - go straight to sign-in.

Docker Compose Example

services:
  primo:
    image: ghcr.io/primocms/primo:latest
    restart: always
    ports:
      - 8080:8080
    volumes:
      - primo-data:/app/pb_data
    environment:
      - PRIMO_APP_URL=https://cms.example.com
      - PRIMO_SUPERUSER_EMAIL=admin@example.com
      - PRIMO_SUPERUSER_PASSWORD=${SUPERUSER_PASSWORD}
      - PRIMO_USER_EMAIL=editor@example.com
      - PRIMO_USER_PASSWORD=${USER_PASSWORD}

volumes:
  primo-data:

Use .env files or secrets management to avoid hardcoding passwords in docker-compose.yml

Railway Template

Railway automatically handles environment variables through their UI:

Deploy using the Railway button
Set environment variables in Railway dashboard
Railway restarts the service automatically

# Railway environment variables
PRIMO_APP_URL=${RAILWAY_STATIC_URL}
PRIMO_SUPERUSER_EMAIL=admin@example.com
PRIMO_SUPERUSER_PASSWORD=<secret>

Security Best Practices

Never commit passwords to version control

Use environment variables, secrets management, or encrypted files. Never hardcode passwords in docker-compose.yml or other config files.

Use strong passwords

Generate random passwords with at least 16 characters:

# Generate a random password
openssl rand -base64 24

Rotate passwords regularly

Change initial passwords after setup, especially for production environments.

Use secrets management

For production deployments, use:

Railway: Built-in secrets
Docker Swarm: Docker secrets
Kubernetes: Kubernetes secrets
Vault: HashiCorp Vault

Limit who has access to environment variables

Environment variables contain sensitive information. Restrict access to deployment configurations.

Troubleshooting

Setup screen appears even with PRIMO_SUPERUSER_EMAIL set

Cause: Environment variables not loaded, or database already initialized Solution:

Check environment variables are correctly set
Verify Docker/Railway configuration
If database exists, delete /app/pb_data volume and restart

Cause: Wrong password, or user wasn’t created Solution:

Check logs for errors during startup
Verify password meets minimum requirements (8 characters)
Check that both EMAIL and PASSWORD variables are set

Variables not taking effect

Cause: Variables only work on first startup Solution: Environment variables for user creation only work when the database is first initialized. To reset:

Stop the container
Delete the volume: docker volume rm primo-data
Restart with new environment variables

Deleting the volume deletes all your data. Only do this for fresh installs or if you have backups.

Getting Started

Building Sites

CLI

Collaboration

Content Management

Dashboard

Reference

Environment Variables

Initial Setup Variables

`PRIMO_SUPERUSER_EMAIL`

`PRIMO_SUPERUSER_PASSWORD`

`PRIMO_USER_EMAIL`

`PRIMO_USER_PASSWORD`

`PRIMO_APP_URL`

Custom Domain Variables

`PRIMO_BASE_DOMAIN`

`PRIMO_DOMAIN_PROVIDER`

`PRIMO_RAILWAY_TOKEN`

Common Configurations

Development Setup

Production with Manual Setup

Production with Automated Setup

Docker Compose Example

Railway Template

Security Best Practices

Troubleshooting

Setup screen appears even with PRIMO_SUPERUSER_EMAIL set

Variables not taking effect

Next Steps

Deployment Guide

Troubleshooting

​Initial Setup Variables

​PRIMO_SUPERUSER_EMAIL

​PRIMO_SUPERUSER_PASSWORD

​PRIMO_USER_EMAIL

​PRIMO_USER_PASSWORD

​PRIMO_APP_URL

​Custom Domain Variables

​PRIMO_BASE_DOMAIN

​PRIMO_DOMAIN_PROVIDER

​PRIMO_RAILWAY_TOKEN

​Common Configurations

​Development Setup

​Production with Manual Setup

​Production with Automated Setup

​Docker Compose Example

​Railway Template

​Security Best Practices

​Troubleshooting

​Setup screen appears even with PRIMO_SUPERUSER_EMAIL set

​Can’t sign in after setting environment variables

​Variables not taking effect

​Next Steps

Deployment Guide

Troubleshooting

Initial Setup Variables

`PRIMO_SUPERUSER_EMAIL`

`PRIMO_SUPERUSER_PASSWORD`

`PRIMO_USER_EMAIL`

`PRIMO_USER_PASSWORD`

`PRIMO_APP_URL`

Custom Domain Variables

`PRIMO_BASE_DOMAIN`

`PRIMO_DOMAIN_PROVIDER`

`PRIMO_RAILWAY_TOKEN`

Common Configurations

Development Setup

Production with Manual Setup

Production with Automated Setup

Docker Compose Example

Railway Template

Security Best Practices

Troubleshooting

Setup screen appears even with PRIMO_SUPERUSER_EMAIL set

Can’t sign in after setting environment variables

Variables not taking effect

Next Steps