Journiv uses environment variables for all configuration. This reference covers every available option.

Required Variables

These variables must be set for Journiv to run:

Variable	Description	Example
`SECRET_KEY`	Secret key for JWT token signing (minimum 32 characters)	`openssl rand -base64 32`
`DOMAIN_NAME`	Your server IP address or domain name	`192.168.1.1` or `journiv.example.com`

Database Configuration

Variable	Default	Description
`DATABASE_URL`	`sqlite:///./journiv.db`	Database connection string
`POSTGRES_HOST`	-	PostgreSQL host (if not using `DATABASE_URL`)
`POSTGRES_USER`	-	PostgreSQL user
`POSTGRES_PASSWORD`	-	PostgreSQL password
`POSTGRES_DB`	-	PostgreSQL database name
`POSTGRES_PORT`	`5432`	PostgreSQL port

Database URL Formats:

SQLite: sqlite:///./journiv.db or sqlite:////absolute/path/to/journiv.db
PostgreSQL: postgresql://user:password@host:5432/journiv

Application Settings

Variable	Default	Description
`ENVIRONMENT`	`development`	Environment mode (`development`, `production`)
`DEBUG`	`false`	Enable debug mode (shows detailed error pages)
`LOG_LEVEL`	`INFO`	Logging level (`DEBUG`, `INFO`, `WARNING`, `ERROR`)
`DOMAIN_SCHEME`	`http`	Domain scheme (`http`, `https`)
`API_V1_PREFIX`	`/api/v1`	API prefix (usually don't change)

Storage Configuration

Journiv uses /data as the default data directory (Docker) or the application directory (manual installation).

Variable	Default	Description
`MEDIA_ROOT`	`/data/media`	Directory for uploaded media files (images, attachments)
`LOG_DIR`	`/data/logs`	Directory for application logs
`EXPORT_DIR`	`/data/exports`	Directory for exported data files
`IMPORT_DIR`	`/data/imports`	Directory for imported data files
`MAX_FILE_SIZE_MB`	`50`	Maximum file upload size in MB
`IMPORT_EXPORT_MAX_FILE_SIZE_MB`	`500`	Maximum import/export file size in MB

Note: The SQLite database file (journiv.db) is stored at /data/journiv.db in Docker installations. For PostgreSQL, the database is managed separately.

Docker Volume Mounts

When using Docker, mount the /data directory to persist data:

Named volume (recommended):

-v journiv_data:/data

Bind mount (for easy file access):

-v /path/to/local/data:/data

Note: When using bind mounts, ensure permissions are set correctly. The container runs as a non-root user (UID 1000), so the mounted directory should be writable by that user.

Security Settings

Variable	Default	Description
`DISABLE_SIGNUP`	`false`	Disable new user registration
`ACCESS_TOKEN_EXPIRE_MINUTES`	`15`	Access token expiry in minutes
`REFRESH_TOKEN_EXPIRE_DAYS`	`7`	Refresh token expiry in days
`ADMIN_USER`	-	Admin user email (for admin exports)
`PASSWORD_MIN_LENGTH`	`8`	Minimum password length

CORS Configuration

Variable	Default	Description
`ENABLE_CORS`	`false`	Enable CORS (required for web app from different domain)
`CORS_ORIGINS`	-	Comma-separated list of allowed origins
`CORS_CREDENTIALS`	`true`	Allow credentials in CORS requests

Example:

ENABLE_CORS=true
CORS_ORIGINS=https://journiv.example.com,https://app.journiv.example.com

OIDC/SSO Configuration

Variable	Default	Description
`OIDC_ENABLED`	`false`	Enable OIDC authentication
`OIDC_ISSUER`	-	OIDC provider issuer URL (e.g., `https://keycloak.example.com/realms/journiv`)
`OIDC_CLIENT_ID`	-	OIDC client ID
`OIDC_CLIENT_SECRET`	-	OIDC client secret
`OIDC_REDIRECT_URI`	-	OIDC redirect URI (usually `https://your-domain.com/api/v1/oidc/callback`)
`OIDC_SCOPES`	`openid email profile`	OIDC scopes (space-separated)
`OIDC_AUTO_PROVISION`	`true`	Auto-create accounts on first OIDC login
`REDIS_URL`	-	Redis URL for OIDC state storage (required for OIDC)

OIDC Example:

OIDC_ENABLED=true
OIDC_ISSUER=https://keycloak.example.com/realms/journiv
OIDC_CLIENT_ID=journiv-client
OIDC_CLIENT_SECRET=your-client-secret
OIDC_REDIRECT_URI=https://journiv.example.com/api/v1/oidc/callback
REDIS_URL=redis://redis:6379/0

Rate Limiting

Variable	Default	Description
`RATE_LIMIT_ENABLED`	`true`	Enable rate limiting
`RATE_LIMIT_PER_MINUTE`	`60`	Requests per minute per IP

Example Configurations

Minimal (SQLite)

SECRET_KEY=your-secret-key-here
DOMAIN_NAME=192.168.1.1

Production (PostgreSQL)

SECRET_KEY=your-secret-key-here
DOMAIN_NAME=journiv.example.com
DATABASE_URL=postgresql://journiv:password@localhost:5432/journiv
ENVIRONMENT=production
LOG_LEVEL=INFO
DEBUG=false
MAX_FILE_SIZE_MB=100
DISABLE_SIGNUP=false

Production with OIDC

SECRET_KEY=your-secret-key-here
DOMAIN_NAME=journiv.example.com
DATABASE_URL=postgresql://journiv:password@localhost:5432/journiv
ENVIRONMENT=production
LOG_LEVEL=INFO
DEBUG=false
OIDC_ENABLED=true
OIDC_ISSUER=https://keycloak.example.com/realms/journiv
OIDC_CLIENT_ID=journiv-client
OIDC_CLIENT_SECRET=your-client-secret
OIDC_REDIRECT_URI=https://journiv.example.com/api/v1/oidc/callback
REDIS_URL=redis://redis:6379/0
DISABLE_SIGNUP=true

Development

SECRET_KEY=dev-secret-key-change-in-production
DOMAIN_NAME=localhost
ENVIRONMENT=development
LOG_LEVEL=DEBUG
DEBUG=true

Environment Variable Priority

Environment variables are read in this order (later overrides earlier):

System environment variables
.env file (for manual installation)
Docker Compose environment section
Docker Compose env_file

Security Best Practices

Never commit .env files - Add to .gitignore
Use strong SECRET_KEY - Generate with openssl rand -base64 32
Rotate secrets regularly - Especially in production
Use different keys per environment - Don't reuse dev keys in production
Store secrets securely - Use secret management tools in production
Limit CORS origins - Only allow trusted domains
Disable signups - Set DISABLE_SIGNUP=true if using OIDC exclusively

Troubleshooting

Variable not taking effect

Check spelling (case-sensitive)
Restart container/service after changes
Verify variable is set: docker compose exec journiv env | grep VARIABLE_NAME

Database connection issues

Verify DATABASE_URL format is correct
Check PostgreSQL is accessible
Verify credentials are correct

OIDC not working

Ensure REDIS_URL is set (required for OIDC)
Verify OIDC_REDIRECT_URI matches provider configuration
Check OIDC_ISSUER is accessible
Verify client credentials are correct

Environment Variables