> ## Documentation Index
> Fetch the complete documentation index at: https://docs.primo.build/llms.txt
> Use this file to discover all available pages before exploring further.
# Environment Variables
> Configure Primo using environment variables for deployment.
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:**
```bash theme={null}
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:**
```bash theme={null}
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:**
```bash theme={null}
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:**
```bash theme={null}
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:**
```bash theme={null}
PRIMO_APP_URL=https://cms.example.com
```
## Common Configurations
### Development Setup
```bash theme={null}
# No environment variables needed
# Just run: docker-compose up
```
The setup screen will guide you through creating your first account.
### Production with Manual Setup
```bash theme={null}
PRIMO_APP_URL=https://cms.example.com
```
Access the setup screen to create your admin account manually.
### Production with Automated Setup
```bash theme={null}
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
```yaml theme={null}
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](https://railway.com/?referralCode=RCPU7k) automatically handles environment variables through their UI:
1. Deploy using the Railway button
2. Set environment variables in Railway dashboard
3. Railway restarts the service automatically
```bash theme={null}
# Railway environment variables
PRIMO_APP_URL=${RAILWAY_STATIC_URL}
PRIMO_SUPERUSER_EMAIL=admin@example.com
PRIMO_SUPERUSER_PASSWORD=
```
## Security Best Practices
Use environment variables, secrets management, or encrypted files. Never hardcode passwords in `docker-compose.yml` or other config files.
Generate random passwords with at least 16 characters:
```bash theme={null}
# Generate a random password
openssl rand -base64 24
```
Change initial passwords after setup, especially for production environments.
For production deployments, use:
* **[Railway](https://railway.com/?referralCode=RCPU7k)**: Built-in secrets
* **Docker Swarm**: Docker secrets
* **Kubernetes**: Kubernetes secrets
* **Vault**: HashiCorp Vault
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**:
1. Check environment variables are correctly set
2. Verify Docker/Railway configuration
3. If database exists, delete `/app/pb_data` volume and restart
### Can't sign in after setting environment variables
**Cause**: Wrong password, or user wasn't created
**Solution**:
1. Check logs for errors during startup
2. Verify password meets minimum requirements (8 characters)
3. 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:
1. Stop the container
2. Delete the volume: `docker volume rm primo-data`
3. Restart with new environment variables
Deleting the volume deletes all your data. Only do this for fresh installs or if you have backups.
## Next Steps
Learn how to deploy Primo to production
Solve common deployment issues