Docker

The Docker configuration for Karrio is the recommended approach for most self-hosting scenarios. This guide will walk you through deploying Karrio using Docker.

Requirements

Make sure you have docker & docker compose installed on your server or local machine:

Docker Engine 20.10.0 or later
Docker Compose V2 (comes with Docker Desktop or can be installed separately)
At least 2GB RAM (4GB+ recommended for production)
At least 20GB of available storage

Note: docker compose (without the hyphen) is now the primary method of using docker-compose, per the Docker documentation.

Getting Started

There are two main ways to deploy Karrio with Docker:

One-click hobby installation - The fastest way to get started
Manual Docker Compose setup - For more customization options

One-Click Hobby Installation

For a quick start with minimal configuration, our one-click installation script is the fastest way to get up and running.

Requirements

A Linux server (Ubuntu 20.04+ recommended)
An instance with at least 2GB of RAM (4GB recommended)
A domain name with DNS configured (for production use)

Setting up the Stack

SSH into your server
Run the following command:

1/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/karrioapi/karrio/HEAD/bin/deploy-hobby)"

When prompted, provide:
- The release tag you want to use (or accept the default)
- Your domain name (for production deployment)
Wait for the setup to complete (~5-10 minutes)
- The script will download required files
- Set up Docker and Docker Compose
- Deploy the full Karrio stack with PostgreSQL, Redis, API, Dashboard, and Caddy
- Configure SSL certificates (if domain provided)

Once complete, you’ll be able to access your Karrio instance at:

Dashboard: https://app.yourdomain.com (or http://localhost:3000 for local deployment)
API: https://api.yourdomain.com (or http://localhost:5002 for local deployment)

Default login credentials: admin@example.com | demo

Customizing Your Deployment

The deployment creates a directory structure with the following key files:

1~/karrio/
2├── .env                # Environment variables
3├── docker-compose.yml  # Docker Compose configuration
4└── Caddyfile           # Caddy web server configuration (for SSL)

To customize your deployment:

Edit the .env file to change environment variables:

1nano ~/karrio/.env

Restart the services to apply changes:

1cd ~/karrio
2docker-compose down
3docker-compose up -d

Manual Docker Compose Setup

If you prefer more control over the installation process, you can set up Karrio manually using Docker Compose.

Steps

Create a directory for your Karrio installation:

1mkdir -p ~/karrio
2cd ~/karrio

Download the Docker Compose file:

1curl -O https://raw.githubusercontent.com/karrioapi/karrio/HEAD/docker/docker-compose.yml

Create a .env file with your configuration:

1cat > .env << EOL
2# Database settings
3DATABASE_ENGINE=postgresql_psycopg2
4DATABASE_NAME=db
5DATABASE_USERNAME=postgres
6DATABASE_PASSWORD=postgres
7DATABASE_HOST=db
8DATABASE_PORT=5432
9
10# Redis settings
11REDIS_HOST=redis
12REDIS_PORT=6379
13
14# API settings
15SECRET_KEY=$(openssl rand -base64 32)
16KARRIO_HTTP_PORT=5002
17
18# Dashboard settings
19DASHBOARD_PORT=3000
20DASHBOARD_URL=http://localhost:3000
21KARRIO_PUBLIC_URL=http://localhost:5002
22JWT_SECRET=$(openssl rand -base64 32)
23
24# Set the Karrio version tag
25KARRIO_TAG=latest
26EOL

Start the services:

1docker-compose up -d

Access your Karrio instance:
- Dashboard: http://localhost:3000
- API: http://localhost:5002

Default login credentials: admin@example.com | demo

Production Deployment with Caddy

For production environments, we recommend using Caddy as a reverse proxy to handle HTTPS and domain routing.

Create a Caddyfile in your deployment directory:

1{
2  email your-email@example.com
3}
4
5api.your-domain.com {
6  reverse_proxy karrio.api:5002
7}
8
9app.your-domain.com {
10  reverse_proxy karrio.dashboard:3000
11}

Update your .env file with your domain information:

1DASHBOARD_URL=https://app.your-domain.com
2KARRIO_PUBLIC_URL=https://api.your-domain.com

Download the hobby Docker Compose file that includes Caddy:

1curl -O https://raw.githubusercontent.com/karrioapi/karrio/HEAD/docker/docker-compose.hobby.yml
2mv docker-compose.hobby.yml docker-compose.yml

Start the stack with Caddy:

1docker-compose up -d

Caddy will automatically obtain and renew SSL certificates for your domains through Let’s Encrypt.

Container Architecture

The Karrio Docker deployment consists of the following containers:

karrio.api: The main API server running on port 5002
karrio.worker: Background worker for processing tasks
karrio.dashboard: Web interface running on port 3000
karrio.db: PostgreSQL database server
karrio.redis: Redis for caching and task queues
karrio.caddy (hobby deployment): Caddy web server for HTTPS and routing

Checking Container Status

You can check the status of all containers using:

1docker-compose ps

All containers should show as “Up” with their respective ports exposed.

Accessing Container Logs

To view logs from a specific container:

1docker-compose logs <container_name>

For example:

1docker-compose logs karrio.api

Add the -f flag to follow logs in real-time:

1docker-compose logs -f karrio.api

Troubleshooting

All Containers Not Running

If some containers aren’t running:

Check the status:

1docker-compose ps

View the logs of the failing container:

1docker-compose logs <container_name>

Database Connection Issues

If you encounter database connection issues:

Check database logs
1docker-compose logs karrio.db
2
3# Connect to the database to verify it's running
4docker-compose exec karrio.db psql -U postgres

API Not Responding

If the API is not responding:

Check API logs
1docker-compose logs karrio.api
2
3# Restart the API service
4docker-compose restart karrio.api

SSL Certificate Issues

If you’re using Caddy and SSL certificates aren’t being issued:

Check Caddy logs
1docker-compose logs karrio.caddy

Common issues include:

DNS records not properly configured
Ports 80/443 not open in your firewall
Incorrect domain name in your configuration

Updating Karrio

For hobby deployments, use our upgrade script:

1/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/karrioapi/karrio/HEAD/bin/upgrade-hobby)"

For manual deployments:

Pull the latest images:

1docker-compose pull

Restart the services:

1docker-compose down
2docker-compose up -d

Managing Data

Data Persistence

Docker volumes are used to persist data:

postgres-data: Database files
redis-data: Redis data
karrio-static: Static files for the web interface
caddy-data: Caddy SSL certificates and configuration

You can view all volumes with:

1docker volume ls

Backing Up Your Data

To back up your database:

1docker-compose exec karrio.db pg_dump -U postgres -d db > karrio_backup_$(date +%Y%m%d).sql

To back up your configuration:

1cp .env .env.backup.$(date +%Y%m%d)
2cp Caddyfile Caddyfile.backup.$(date +%Y%m%d) # if using Caddy

Stopping and Starting Services

To stop all services:

1docker-compose down

To start them again:

1docker-compose up -d

To restart a specific service:

1docker-compose restart <service_name>

Getting Started

Deployments

Guides

Docker

Requirements

Getting Started

One-Click Hobby Installation

Requirements

Setting up the Stack

Customizing Your Deployment

Manual Docker Compose Setup

Steps

Production Deployment with Caddy

Container Architecture

Checking Container Status

Accessing Container Logs

Troubleshooting

All Containers Not Running

Database Connection Issues

API Not Responding

SSL Certificate Issues

Updating Karrio

Managing Data

Data Persistence

Backing Up Your Data

Stopping and Starting Services