Environment Variables

Copy for LLM

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. You can configure Redis using either a connection URL (recommended) or individual parameters.

Variable	Description	Default	Required
REDIS_URL	Complete Redis connection URL (e.g., redis://user:pass@host:port)	None	No
REDIS_HOST	Redis host (used if REDIS_URL not set)	None	No
REDIS_PORT	Redis port (used if REDIS_URL not set)	6379	No
REDIS_PASSWORD	Redis password (used if REDIS_URL not set)	None	No
REDIS_USERNAME	Redis username (used if REDIS_URL not set)	default	No
REDIS_SSL	Enable SSL/TLS for Redis connection	False	No
REDIS_PREFIX	Key prefix for cached data	karrio	No

Note: REDIS_URL takes precedence over individual parameters. If REDIS_URL is set, it will supersede all individual Redis parameters (REDIS_HOST, REDIS_PORT, etc.). Use rediss:// scheme in the URL for SSL connections.

Examples:

• Without SSL: REDIS_URL=redis://localhost:6379
• With SSL: REDIS_URL=rediss://user:password@redis-host:6380/0
• With individual params: REDIS_HOST=localhost REDIS_PORT=6379 REDIS_SSL=True

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 & Tasks Configuration

These variables configure Huey background workers for async task processing (shipment tracking, webhooks, etc.).

Variable	Description	Default	Required
BACKGROUND_WORKERS	Number of background worker processes	2	No
DETACHED_WORKER	Run workers in detached mode (separate from API process)	False	No
WORKER_IMMEDIATE_MODE	Execute tasks immediately (useful for testing)	False	No
WORKER_DB_DIR	Directory for SQLite task database (when Redis not available)	/data	No
TRACKING_PULSE	Interval in seconds for automatic shipment tracking updates	7200	No
DEFAULT_SCHEDULER_RUN_INTERVAL	Interval in seconds for scheduled task checks	3600	No

Background Worker Modes:

• Redis Mode (recommended for production): When Redis is configured, Huey uses Redis for task queue management. This allows multiple worker processes to share tasks.
• SQLite Mode (development/single instance): When Redis is not configured, Huey uses SQLite for task storage. This mode is suitable for development or single-instance deployments.
• Immediate Mode: When WORKER_IMMEDIATE_MODE=True, tasks execute synchronously in the same process. Useful for debugging.

Dashboard Configuration

These variables configure the Karrio dashboard.

Variable	Description	Default	Required
DASHBOARD_PORT	HTTP port for the dashboard	3002	No
DASHBOARD_URL	Public URL for the dashboard	http://localhost:3002	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
KARRIO_PLUGINS	Host path for mounting plugins	./plugins	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

Observability Configuration (OpenTelemetry)

Karrio supports OpenTelemetry for distributed tracing, metrics, and logging. This allows you to monitor your Karrio deployment’s performance and troubleshoot issues across services.

Variable	Description	Default	Required
OTEL_ENABLED	Enable OpenTelemetry instrumentation	False	No
OTEL_SERVICE_NAME	Service name for traces and metrics	karrio-api	No
OTEL_EXPORTER_OTLP_ENDPOINT	OTLP exporter endpoint (e.g., http://jaeger:4317)	None	Yes (if OTEL_ENABLED=True)
OTEL_EXPORTER_OTLP_PROTOCOL	Protocol for OTLP exporter (grpc or http)	grpc	No
OTEL_EXPORTER_OTLP_HEADERS	Headers for OTLP exporter (comma-separated key=value pairs)	None	No
OTEL_ENVIRONMENT	Environment name for telemetry data (e.g., production, staging)	production	No
OTEL_RESOURCE_ATTRIBUTES	Additional resource attributes (comma-separated key=value pairs)	None	No

For detailed setup instructions, supported backends, and configuration examples, see the OpenTelemetry documentation.

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 (Option 1: Using REDIS_URL - recommended)
15REDIS_URL=redis://redis:6379
16
17# Redis settings (Option 2: Individual parameters - alternative)
18# REDIS_HOST=redis
19# REDIS_PORT=6379
20# REDIS_SSL=False
21# REDIS_PASSWORD=your_redis_password  # if required
22# REDIS_USERNAME=default              # if required
23
24# API settings
25KARRIO_PUBLIC_URL=https://api.yourdomain.com
26KARRIO_WORKERS=4
27
28# Background worker settings
29BACKGROUND_WORKERS=2
30DETACHED_WORKER=True
31TRACKING_PULSE=7200  # 2 hours in seconds
32
33# Dashboard settings
34DASHBOARD_URL=https://app.yourdomain.com
35JWT_SECRET=your_secure_jwt_secret
36
37# Email settings
38EMAIL_HOST=smtp.provider.com
39EMAIL_PORT=587
40EMAIL_HOST_USER=your_email@provider.com
41EMAIL_HOST_PASSWORD=your_email_password
42EMAIL_USE_TLS=True
43DEFAULT_FROM_EMAIL=karrio@yourdomain.com
44
45# Admin account
46ADMIN_EMAIL=admin@yourdomain.com
47ADMIN_PASSWORD=your_secure_admin_password
48
49# Plugin mounting
50KARRIO_PLUGINS=./plugins
51
52# Carrier credentials - USPS example
53USPS_USERNAME=your_usps_username
54USPS_PASSWORD=your_usps_password
55USPS_TEST_MODE=False

Redis SSL/TLS Configuration Examples

For secure Redis connections (common with managed Redis services like AWS ElastiCache, Azure Cache, or Redis Enterprise), use these configurations:

Using REDIS_URL with SSL

AWS ElastiCache example (rediss:// scheme for SSL)
1REDIS_URL=rediss://master.your-cluster.cache.amazonaws.com:6380/0
2
3# Azure Cache for Redis example with password
4REDIS_URL=rediss://:your_access_key@your-cache.redis.cache.windows.net:6380/0
5
6# Redis Enterprise Cloud example with username and password
7REDIS_URL=rediss://default:your_password@redis-endpoint.cloud.redislabs.com:12345/0

Using Individual Parameters with SSL

Managed Redis with SSL enabled
1REDIS_HOST=master.your-cluster.cache.amazonaws.com
2REDIS_PORT=6380
3REDIS_SSL=True
4REDIS_PASSWORD=your_redis_password
5REDIS_USERNAME=default

Important Notes:

• Most managed Redis services use port 6380 for SSL connections and port 6379 for non-SSL
• The rediss:// scheme (with double ‘s’) in REDIS_URL automatically enables SSL
• When using individual parameters, set REDIS_SSL=True to enable SSL
• Some providers (like Azure) require authentication - include credentials in the URL or via separate parameters

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.