Karrio Insiders Setup

Karrio Insiders is the enterprise-ready shipping integration platform built on top of Karrio. This guide will walk you through the installation and initial setup of Karrio Insiders.

Prerequisites

Before beginning the installation, ensure you have:

Docker and Docker Compose installed on your system
GitHub Personal Access Token (PAT) with read:packages scope
Valid Karrio Insiders subscription from karrio.io
Domain name (for production deployments)
SSL certificates (for production deployments)

Authentication Setup

First, you’ll need to authenticate with the GitHub Container Registry to access Karrio Insiders images.

Creating a GitHub Personal Access Token

Navigate to GitHub Settings → Developer settings → Personal access tokens
Click “Generate new token (classic)”
Give your token a descriptive name (e.g., “Karrio Insiders Access”)
Select the read:packages scope
Click “Generate token” and save it securely

Logging into GitHub Container Registry

1echo YOUR_PAT | docker login ghcr.io -u YOUR_GITHUB_USERNAME --password-stdin

Replace YOUR_PAT with your personal access token and YOUR_GITHUB_USERNAME with your GitHub username.

Installation Methods

Quick Start with Docker Compose

For development or testing environments:

Clone the repository

1git clone https://github.com/karrioapi/karrio
2git submodule update --init community
3git submodule update --init ee/insiders
4cd karrio/docker

Start the services

1docker compose -f docker-compose.insiders.yml up -d

Access the platform
- Dashboard: http://localhost:3000
- API: http://localhost:5002
- Default credentials: admin@example.com / demo

The Docker setup includes these services:

API: Karrio server (port 5002)
Worker: Background task processor
Dashboard: Web interface (port 3000)
Database: PostgreSQL database
Redis: Caching and task queue
Caddy: Reverse proxy (ports 80/443)

Production Deployment

For production environments, you’ll need to:

Set up your own server infrastructure
Configure Docker and Docker Compose
Set up SSL certificates (e.g., using Let’s Encrypt)
Configure your domain DNS settings
Set up PostgreSQL and Redis databases
Configure environment variables for production

Environment Configuration

Essential Environment Variables

Create a .env file in your deployment directory:

1############
2# Secrets - CHANGE THESE BEFORE PRODUCTION
3############
4SECRET_KEY=your-secret-jwt-token-with-at-least-32-characters-long
5JWT_SECRET=your-secret-jwt-token-with-at-least-32-characters-long
6
7############
8# Database Configuration
9############
10DATABASE_HOST=db
11DATABASE_NAME=db
12DATABASE_PORT=5432
13DATABASE_USERNAME=postgres
14DATABASE_PASSWORD=postgres
15DATABASE_ENGINE=postgresql
16
17############
18# Redis Cache Configuration
19############
20REDIS_HOST=redis
21REDIS_PORT=6379
22# REDIS_PASSWORD=redis  # uncomment if using password
23
24############
25# API Configuration
26############
27KARRIO_TAG=2025.5rc6
28KARRIO_HTTP_PORT=5002
29
30############
31# Dashboard Configuration
32############
33DASHBOARD_PORT=3000
34DASHBOARD_URL=http://localhost:3000
35KARRIO_PUBLIC_URL=http://localhost:5002
36
37############
38# General Settings
39############
40ENABLE_ALL_PLUGINS_BY_DEFAULT=True
41JWT_ACCESS_EXPIRY=30  # in minutes
42ALLOW_SIGNUP=false
43ALLOW_ADMIN_APPROVED_SIGNUP=false
44PERSIST_SDK_TRACING=true
45
46############
47# Email Configuration (optional)
48############
49EMAIL_PORT=587
50EMAIL_USE_TLS=true
51EMAIL_HOST=smtp.gmail.com
52EMAIL_HOST_USER=your-email@company.com
53EMAIL_HOST_PASSWORD=your-app-password

Production Configuration

For production deployments, update your .env file with production values:

1############
2# Production URLs
3############
4DASHBOARD_URL=https://app.yourcompany.com
5KARRIO_PUBLIC_URL=https://api.yourcompany.com
6
7############
8# Production Database (use managed service)
9############
10DATABASE_HOST=your-db-host.com
11DATABASE_NAME=karrio_prod
12DATABASE_USERNAME=karrio_user
13DATABASE_PASSWORD=secure-database-password
14
15############
16# Production Redis (use managed service)
17############
18REDIS_HOST=your-redis-host.com
19REDIS_PORT=6379
20REDIS_PASSWORD=secure-redis-password
21
22############
23# Email Configuration (use service like SendGrid or Resend)
24############
25EMAIL_HOST=smtp.sendgrid.net
26EMAIL_PORT=587
27EMAIL_USE_TLS=true
28EMAIL_HOST_USER=apikey
29EMAIL_HOST_PASSWORD=your-sendgrid-api-key
30
31############
32# Security Settings
33############
34ALLOW_SIGNUP=false
35ALLOW_ADMIN_APPROVED_SIGNUP=true
36PERSIST_SDK_TRACING=false  # disable in production for performance

Verifying Installation

After deployment, verify your installation:

Check service health

1docker compose -f docker-compose.insiders.yml ps
2docker compose -f docker-compose.insiders.yml logs -f api

Run diagnostics

1docker compose -f docker-compose.insiders.yml exec api karrio check --deploy

Test API connectivity
```
1curl -X GET http://localhost:5002/
```

Initial Configuration

After successful installation:

Change default credentials immediately
Configure your superadmin account (see Quickstart Guide)
Set up SSL certificates if not using the automated script
Configure backup procedures for the database
Set up monitoring (optional but recommended)

Troubleshooting

Common Issues

Authentication Errors

Error: denied: permission_denied: read_packages scope is required

Solution: Ensure your GitHub PAT has the read:packages scope enabled.

Port Conflicts

Error: bind: address already in use

Solution: Change the port mappings in docker-compose.yml or stop conflicting services.

Database Connection Issues

django.db.utils.OperationalError: could not connect to server

Solution: Ensure the database container is running and healthy:

1docker compose -f docker-compose.insiders.yml ps db
2docker compose -f docker-compose.insiders.yml logs db

Getting Help

Documentation: karrio.io/docs
Discord Community: Join our Discord
Email Support: support@karrio.io (Insiders subscribers)

Next Steps

Once your Karrio Insiders instance is running:

Set up your superadmin account - Configure the initial admin user
Configure white labeling - Customize the platform appearance
Manage feature flags - Enable/disable platform features
Set up carriers - Configure shipping carrier integrations

Security Considerations

Always use HTTPS in production
Regularly update Docker images
Use strong passwords for all accounts
Enable audit logging for compliance
Implement proper backup strategies
Consider using a Web Application Firewall (WAF)

Getting Started