Environment Variables

This page provides a comprehensive reference for all environment variables you can use to configure your self-hosted Karrio instance.

Core Configuration

These variables control the basic functionality of your Karrio installation.

Variable	Description	Default	Required
SECRET_KEY	Django secret key used for cryptographic signing	Random string	Yes
DEBUG_MODE	Enable debug mode (not recommended in production)	False	No
USE_HTTPS	Enable HTTPS support	False	No
DOMAIN	Your domain name	localhost	Yes (for production)
ALLOWED_HOSTS	Comma-separated list of allowed hosts	*	No

Database Configuration

These variables configure the PostgreSQL database connection.

Variable	Description	Default	Required
DATABASE_ENGINE	Database engine to use	postgresql_psycopg2	Yes
DATABASE_NAME	Database name	db	Yes
DATABASE_USERNAME	Database user	postgres	Yes
DATABASE_PASSWORD	Database password	postgres	Yes
DATABASE_HOST	Database host	db	Yes
DATABASE_PORT	Database port	5432	Yes

Redis Configuration

Redis is used for caching and background task management.

Variable	Description	Default	Required
REDIS_HOST	Redis host	redis	Yes
REDIS_PORT	Redis port	6379	Yes
REDIS_PASSWORD	Redis password (if required)	None	No
REDIS_DB	Redis database number	1	No

API Configuration

These variables configure the Karrio API server.

Variable	Description	Default	Required
KARRIO_HTTP_PORT	HTTP port for the API server	5002	No
KARRIO_PUBLIC_URL	Public URL for the API	http://localhost:5002	Yes (for production)
KARRIO_WORKERS	Number of API workers	2	No
BACKGROUND_WORKERS	Number of background workers	2	No
DETACHED_WORKER	Run worker in detached mode	False	No

Dashboard Configuration

These variables configure the Karrio dashboard.

Variable	Description	Default	Required
DASHBOARD_PORT	HTTP port for the dashboard	3000	No
DASHBOARD_URL	Public URL for the dashboard	http://localhost:3000	Yes (for production)
NEXTAUTH_SECRET	Secret key for NextAuth (dashboard auth)	Same as JWT_SECRET	Yes
JWT_SECRET	Secret key for JWT tokens	Random string	Yes

Email Configuration

These variables configure email sending for notifications.

Variable	Description	Default	Required
EMAIL_HOST	SMTP server host	None	No
EMAIL_PORT	SMTP server port	587	No
EMAIL_HOST_USER	SMTP username	None	No
EMAIL_HOST_PASSWORD	SMTP password	None	No
EMAIL_USE_TLS	Use TLS for SMTP connection	True	No
DEFAULT_FROM_EMAIL	Default sender email address	noreply@localhost	No

Admin Account

These variables configure the default admin account created on first startup.

Variable	Description	Default	Required
ADMIN_EMAIL	Admin user email	admin@example.com	No
ADMIN_PASSWORD	Admin user password	demo	No

File Storage

These variables configure where files are stored.

Variable	Description	Default	Required
WORK_DIR	Working directory for the API	/karrio/app	No
LOG_DIR	Directory for log files	/karrio/log	No
WORKER_DB_DIR	Directory for worker databases	/karrio/data	No
STATIC_ROOT_DIR	Directory for static files	/karrio/static	No

Advanced Configuration

These variables enable advanced features and optimizations.

Variable	Description	Default	Required
LOG_LEVEL	Logging level (DEBUG, INFO, WARNING, ERROR)	INFO	No
SENTRY_DSN	Sentry DSN for error monitoring	None	No
CORS_ALLOWED_ORIGINS	Comma-separated list of allowed CORS origins	*	No
MAX_UPLOAD_SIZE	Maximum upload size in MB	10	No
THROTTLE_RATE	API throttle rate (requests/minute)	None	No
CACHE_TIMEOUT	Cache timeout in seconds	300	No

Example .env File

Here’s a complete example of a .env file for a production deployment:

Core settings
1SECRET_KEY=your_secure_secret_key
2DEBUG_MODE=False
3USE_HTTPS=True
4DOMAIN=karrio.yourdomain.com
5
6# Database settings
7DATABASE_ENGINE=postgresql_psycopg2
8DATABASE_NAME=karrio
9DATABASE_USERNAME=karrio_user
10DATABASE_PASSWORD=your_secure_db_password
11DATABASE_HOST=db
12DATABASE_PORT=5432
13
14# Redis settings
15REDIS_HOST=redis
16REDIS_PORT=6379
17
18# API settings
19KARRIO_PUBLIC_URL=https://api.yourdomain.com
20KARRIO_WORKERS=4
21BACKGROUND_WORKERS=2
22DETACHED_WORKER=True
23
24# Dashboard settings
25DASHBOARD_URL=https://app.yourdomain.com
26JWT_SECRET=your_secure_jwt_secret
27
28# Email settings
29EMAIL_HOST=smtp.provider.com
30EMAIL_PORT=587
31EMAIL_HOST_USER=your_email@provider.com
32EMAIL_HOST_PASSWORD=your_email_password
33EMAIL_USE_TLS=True
34DEFAULT_FROM_EMAIL=karrio@yourdomain.com
35
36# Admin account
37ADMIN_EMAIL=admin@yourdomain.com
38ADMIN_PASSWORD=your_secure_admin_password
39
40# Carrier credentials - USPS example
41USPS_USERNAME=your_usps_username
42USPS_PASSWORD=your_usps_password
43USPS_TEST_MODE=False

Environment Variables in Docker

When using Docker, there are multiple ways to set environment variables:

1. Docker Compose: Add environment variables in the docker-compose.yml file under the appropriate service:

1services:
2  api:
3    environment:
4      SECRET_KEY: your_secure_secret_key
5      DEBUG_MODE: "False"
6      # other variables

2. Environment Files: Use an .env file in the same directory as your docker-compose.yml file. Docker Compose will automatically load these variables.

3. Command Line: Pass variables through the command line when running containers:

1docker-compose up -d -e SECRET_KEY=your_secure_secret_key

Best Practices

1. Security: Never commit sensitive environment variables to your repository. Use .env files that are added to your .gitignore.

2. Production vs. Development: Maintain separate environment files for different environments.

3. Secret Management: For production deployments, consider using a secret management service like AWS Secrets Manager, GCP Secret Manager, or HashiCorp Vault.

4. Documentation: Document any custom environment variables you create for your specific deployment or extensions.