Environment Variables

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

Required Variables

These variables must be set for Journiv to run:

Database Configuration

Database URL Formats:

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

Application Settings

Storage Configuration

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

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 app_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

CORS Configuration

Example:

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

OIDC/SSO Configuration

Note: REDIS_URL is required when OIDC is enabled. Redis is used to store OIDC state during the authentication flow.

For complete OIDC setup instructions, including provider-specific configuration (Keycloak, Authentik, Authelia), see the OIDC/SSO Authentication guide.

Hostname & Domain Validation

Journiv uses the DOMAIN_NAME and CORS_ORIGINS to validate incoming requests and prevent HTTP Host header attacks.

Wildcard Support

If you want to support multiple subdomains or any address in your network (e.g., Tailscale), you can use a wildcard:

DOMAIN_NAME=*.ts.net

Important: If using a wildcard for DOMAIN_NAME, you must explicitly set OIDC_REDIRECT_URI to a concrete address (e.g., https://host.vh.ts.net:8668/api/v1/auth/oidc/callback) if OIDC is enabled.

Multiple Specific Hosts

To allow access via multiple specific hostnames (e.g., MagicDNS and a local IP), use CORS_ORIGINS:

ENABLE_CORS=true
CORS_ORIGINS=http://host.vh.ts.net:8668,http://192.168.1.50:8668

When ENABLE_CORS is active, Journiv automatically extracts hostnames from all origins in CORS_ORIGINS and adds them to its trusted hosts list.

Port Support

You can include the public port in DOMAIN_NAME (e.g., DOMAIN_NAME=host.vh.ts.net:8668). Journiv correctly handles this for both hostname validation and absolute URL generation.

Rate Limiting

External API Configuration

Weather Service (OpenWeather)

Weather Service Configuration:

• Weather features are optional - if neither API key is configured, weather features will be disabled
• Get your free API key at: https://openweathermap.org/api
• When configured, users can fetch weather data for locations in their journal entries

API Key Options:

• Only OPEN_WEATHER_API_KEY_25: Enables current weather for new entries (historical weather unavailable)
• Only OPEN_WEATHER_API_KEY_30: Enables both current and historical weather (uses 3.0 API for all requests)
• Both keys configured: Optimal setup - uses 2.5 API for current weather (more efficient) and 3.0 API for historical weather
• Note: You can set the same API key for both 2.5 and 3.0 if you want to use the same API key for both.

Note: OpenWeather 3.0 API (Time Machine) is required to fetch weather for past entries. The free tier includes limited historical weather calls. For more details, see the Weather & Location guide.

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
OPEN_WEATHER_API_KEY_25=your-openweather-2-5-api-key-here
OPEN_WEATHER_API_KEY_30=your-openweather-3-0-api-key-here

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/auth/oidc/callback
REDIS_URL=redis://redis:6379/0
DISABLE_SIGNUP=true

For complete OIDC setup instructions, see the OIDC/SSO Authentication guide.

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):

1. System environment variables
2. .env file (for manual installation)
3. Docker Compose environment section
4. Docker Compose env_file

Security Best Practices

1. Never commit .env files - Add to .gitignore
2. Use strong SECRET_KEY - Generate with openssl rand -base64 32
3. Rotate secrets regularly - Especially in production
4. Use different keys per environment - Don't reuse dev keys in production
5. Store secrets securely - Use secret management tools in production
6. Limit CORS origins - Only allow trusted domains
7. Disable signups - Set DISABLE_SIGNUP=true to require admin-created accounts only (blocks OIDC auto-provisioning too)

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