Environment Variables

Complete reference for Wraft environment variables and configuration options

We use environment variables to manage configuration. There is a file called .env.example in the root directory of this project with all the environment variables set to empty values. You can set the correct values as per the following options. Once you set the values, you should rename the file to .env before you start the server.

Application URLs - For frontend and backend (required)

Provide your Wraft domain URLs for frontend and backend services.

export FRONTEND_URL=http://localhost:3000
export BACKEND_URL=http://localhost:4000

Secret key base

For production deployment, you have to set the following variables:

export SECRET_KEY_BASE=mHUYpR7Q1LtBo5eUCt/U6Vluj7gDARoMztdmRgyb8AyZcJN8EspidYIM3W5th8sW

You can generate SECRET_KEY_BASE using mix phx.gen.secret command from the project root folder.

Guardian - Authentication

Configure Guardian for authentication:

export GUARDIAN_KEY=qKeHozNfIjr2Q8QvQYAm+HwoyDNz0t4yUsE8uEtEP6gp4pOnCtLXsvHDCACcdkE3

Generate this using mix guardian.gen.secret

CLOAK_KEY - Sensitive data encryption

export CLOAK_KEY=iPE4i9NkhUnIJMYA5yvs94D++WPcQ1iMTjavh3FS4AU=

Generate this using openssl rand -base64 32

Mailer configuration

export WRAFT_HOSTNAME=example.com

Application Mode

export MIX_ENV=dev
export SELF_HOSTED=true

Database - PostgreSQL

Development Environment

export DEV_DB_USERNAME=postgres
export DEV_DB_PASSWORD=postgres
export DEV_DB_NAME=wraft_dev_temp
export DEV_DB_HOST=localhost
export DEV_DB_PORT=5432

Production Environment

export DATABASE_URL=postgres://postgres:postgres@localhost:5432/wraft_dev_temp

Example: postgres://<username>:<password>@<host>:<port>/<database>

Phoenix - Application Server Configuration

export PHX_SERVER=true
export RELEASE_NAME=wraft_doc

MinIO - Object Storage

Configure MinIO for file storage:

export MINIO_URL=127.0.0.1:9000
export MINIO_HOST=127.0.0.1
export MINIO_PORT=9000
export MINIO_BUCKET=wraft
export MINIO_ROOT_USER=minioadmin
export MINIO_ROOT_PASSWORD=minioadmin

Resend - Email Service

Visit https://resend.com to generate or manage your API key.

export RESEND_API_KEY=your_resend_api_key_here

Optional - Admin Credentials

export WRAFT_ADMIN_EMAIL=wraft_admin_email
export WRAFT_ADMIN_PASSWORD=wraft_admin_password

PDF Tools - File Paths

export WKHTMLTOPDF_PATH=
export PDFTK_PATH=

Sentry - Error Tracking

export SENTRY_DSN=https://public_key@app.getsentry.com/1

Typesense - Search Service

export TYPESENSE_API_KEY=xyz
export TYPESENSE_HOST=localhost
export TYPESENSE_PORT=8108
export TYPESENSE_SCHEME=http

Signing - Digital Signature

Optional configuration for digital signatures:

# OPTIONAL: The local file path to the .p12 file to use stored in priv/keystore/ path.
export SIGNING_LOCAL_FILE_PATH=
# OPTIONAL: The passphase for the .p12 file.
export SIGNING_LOCAL_PASSPHRASE=
# OPTIONAL: The key alias to use for the .p12 file.
export SIGNING_KEY_ALIAS="1"

xelatex variables

export XELATEX_PATH=xelatex

Configuration Examples

Development Environment

For local development, you can use the following minimal configuration:

# Application URLs
export FRONTEND_URL=http://localhost:3000
export BACKEND_URL=http://localhost:4000
 
# Secrets (generate these)
export SECRET_KEY_BASE=$(mix phx.gen.secret)
export GUARDIAN_KEY=$(mix guardian.gen.secret)
export CLOAK_KEY=$(openssl rand -base64 32)
 
# Database
export DATABASE_URL=postgres://postgres:postgres@localhost:5432/wraft_dev
 
# MinIO
export MINIO_ROOT_USER=minioadmin
export MINIO_ROOT_PASSWORD=minioadmin
 
# Typesense
export TYPESENSE_API_KEY=xyz
 
# Application Mode
export MIX_ENV=dev
export SELF_HOSTED=true

Production Environment

For production deployment, ensure all required variables are properly configured:

# Application URLs
export FRONTEND_URL=https://your-wraft-domain.com
export BACKEND_URL=https://api.your-wraft-domain.com
 
# Secrets (generate these)
export SECRET_KEY_BASE=your_production_secret_key
export GUARDIAN_KEY=your_production_guardian_key
export CLOAK_KEY=your_production_cloak_key
 
# Database
export DATABASE_URL=postgres://username:password@host:port/database
 
# MinIO
export MINIO_URL=your-minio-host:9000
export MINIO_HOST=your-minio-host
export MINIO_ROOT_USER=your-minio-user
export MINIO_ROOT_PASSWORD=your-minio-password
 
# Email
export RESEND_API_KEY=your_resend_api_key
export WRAFT_HOSTNAME=your-domain.com
 
# Search
export TYPESENSE_API_KEY=your_typesense_api_key
export TYPESENSE_HOST=your-typesense-host
export TYPESENSE_SCHEME=https
 
# Application Mode
export MIX_ENV=prod
export SELF_HOSTED=true
export PHX_SERVER=true

Security Considerations

Never commit sensitive environment variables to version control
Use strong, unique secrets for production deployments
Rotate secrets regularly for enhanced security
Use environment-specific configurations for different deployment stages
Validate all required variables are set before starting the application

Troubleshooting

If you encounter configuration issues:

Check all required variables are properly set
Verify database connectivity using the provided DATABASE_URL
Ensure MinIO is accessible and credentials are correct
Validate Typesense connection and API key
Check application logs for specific error messages

For more detailed troubleshooting, see the Troubleshooting guide.

Environment Variables