📖 Looking for karrio's legacy docs? Visit docs.karrio.io

Server Installation (No Docker)

The server installation method allows you to deploy the Karrio server directly on your system without using containers. This approach is ideal for environments where Docker is not available or when you prefer direct system installation.

Overview

Server installation deploys the Karrio server components directly on your system using Python. This method provides:

  • Direct system access - Full control over the installation environment
  • No container overhead - Direct resource utilization
  • Custom system integration - Easier integration with existing system services
  • Simplified debugging - Direct access to logs and processes

Requirements

System Requirements

  • Operating System: Ubuntu 20.04+, CentOS 8+, or macOS 10.15+
  • Memory: At least 4GB RAM (recommended for production)
  • Storage: At least 10GB of available disk space
  • Network: Internet access for package downloads

Software Dependencies

The deployment script will automatically install:

  • Python: 3.12.10 (via pyenv)

External services required (not installed by the script):

  • PostgreSQL: 12+ (for data persistence)
  • Redis: 6+ (for caching and task queues)

Installation

Quick Installation (Recommended)

The fastest way to get started is using our automated deployment script:

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

Manual Installation

For more control over the installation process, you can install manually:

1. Install System Dependencies

First, install the required system libraries for document generation (weasyprint) and barcode generation (pyzint):

Download and run the install-binaries script
1curl -fsSL https://raw.githubusercontent.com/karrioapi/karrio/HEAD/bin/install-binaries | bash

Or install manually:

For macOS:

1brew install gcc pango libffi ghostscript zint

For Linux (Ubuntu/Debian):

1apt update -y && apt install -y \
2    libpango-1.0-0 \
3    libharfbuzz0b \
4    libpangoft2-1.0-0 \
5    libharfbuzz-subset0 \
6    gcc \
7    ghostscript \
8    libffi-dev \
9    libjpeg-dev \
10    libopenjp2-7-dev \
11    zint \
12    curl

2. Set up Python Environment

Install Python 3.12.10 using pyenv or your preferred method:

Install pyenv (if not already installed)
1curl https://pyenv.run | bash
2
3# Install Python 3.12.10
4pyenv install 3.12.10
5pyenv global 3.12.10
6
7# Verify installation
8python3 --version

3. Install Karrio Packages

Download and install the required Python packages:

Download requirements.txt
1curl -s https://raw.githubusercontent.com/karrioapi/karrio/main/requirements.txt -o requirements.txt
2
3# Install packages with relaxed compiler flags (handles pyzint compilation issues)
4CFLAGS="-Wno-error=array-bounds -Wno-error=stringop-overflow -Wno-error=incompatible-pointer-types" \
5    python3 -m pip install -r requirements.txt

Note: The CFLAGS environment variable is used to handle compilation issues with certain packages like pyzint. This ensures a smooth installation process.

4. Set up Working Directory

Create the necessary directories and download configuration files:

Create working directories
1mkdir -p ~/.karrio/{app,log,data,static}
2
3# Download configuration files
4curl -s https://raw.githubusercontent.com/karrioapi/karrio/main/apps/api/gunicorn-cfg.py -o ~/.karrio/app/gunicorn-cfg.py
5curl -s https://raw.githubusercontent.com/karrioapi/karrio/main/.env.sample -o ~/.karrio/.env
6
7# Move to working directory
8cd ~/.karrio

What the Scripts Do

The deployment script automatically:

  1. Sets up Python environment - Installs pyenv and Python 3.12.10
  2. Installs system dependencies - Required libraries for document generation and barcode support
  3. Downloads requirements.txt - Gets the latest PyPI package versions from the specified branch
  4. Installs Karrio packages - All server packages from PyPI with proper compiler flags
  5. Configures the environment - Sets up working directories and downloads configuration files

Note: The script only installs the Karrio server packages. It does not deploy PostgreSQL, Redis, or other external services. You must provide these services separately and configure the environment variables accordingly.

Branch-Specific Installation

To install a specific branch or version:

Install from a specific branch
1KARRIO_BRANCH=develop /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/karrioapi/karrio/HEAD/bin/deploy)"
2
3# Or pass branch as argument
4/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/karrioapi/karrio/HEAD/bin/deploy)" main

Configuration

Environment Variables

Edit the environment configuration to point to your external services:

1nano ~/.karrio/.env

Key configuration variables:

Database settings - Point to your PostgreSQL instance
1DATABASE_ENGINE=postgresql_psycopg2
2DATABASE_NAME=karrio
3DATABASE_USERNAME=karrio_user
4DATABASE_PASSWORD=your_secure_password
5DATABASE_HOST=localhost  # Or your PostgreSQL host
6DATABASE_PORT=5432
7
8# Redis settings - Point to your Redis instance
9REDIS_HOST=localhost  # Or your Redis host
10REDIS_PORT=6379
11
12# API settings
13SECRET_KEY=your_secret_key_here
14KARRIO_HTTP_PORT=5002
15
16# Admin settings (for initial setup)
17ADMIN_EMAIL=admin@example.com
18ADMIN_PASSWORD=your_admin_password
19
20# Workers configuration
21KARRIO_WORKERS=2
22BACKGROUND_WORKERS=2

Important: Update the DATABASE_HOST and REDIS_HOST to point to your actual PostgreSQL and Redis instances. These can be:

  • Local installations (localhost)
  • Remote database servers
  • Cloud database services (AWS RDS, Google Cloud SQL, etc.)
  • Managed Redis services (AWS ElastiCache, Redis Cloud, etc.)

Server Setup

Before starting the server, you need to initialize the database and create the initial admin user:

1. Run Database Migrations

1cd ~/.karrio
2karrio migrate

2. Collect Static Files

1karrio collectstatic --noinput

3. Create Initial Admin User

Interactive method
1karrio createsuperuser

Running the Server

Start API Server and Worker Separately

This approach gives you better control and monitoring capabilities:

Terminal 1 - API Server:

Activate the environment (if using pyenv)
1export PATH="$HOME/.pyenv/bin:$PATH"
2eval "$(pyenv init --path)"
3eval "$(pyenv init -)"
4
5# Start the API server
6cd ~/.karrio
7gunicorn --config app/gunicorn-cfg.py karrio.server.asgi -k karrio.server.workers.UvicornWorker

Terminal 2 - Background Worker:

Activate the environment
1export PATH="$HOME/.pyenv/bin:$PATH"
2eval "$(pyenv init --path)"
3eval "$(pyenv init -)"
4
5# Start the background worker
6cd ~/.karrio
7karrio run_huey -w 2  # -w specifies number of worker processes

Monitoring and Logs

Check Service Status

Check if services are running
1ps aux | grep -E "(gunicorn|karrio)"
2
3# Check specific processes
4pgrep -f "gunicorn.*karrio"
5pgrep -f "karrio run_huey"

View Logs

API server logs (if running directly)
1tail -f ~/.karrio/log/karrio.log
2
3# Worker logs
4tail -f ~/.karrio/log/worker.log
5
6# With systemd
7journalctl -u karrio-api -f
8journalctl -u karrio-worker -f

Troubleshooting

Common Issues

Installation Issues

Verify system dependencies
1# macOS
2brew list | grep -E "(gcc|pango|libffi|ghostscript|zint)"
3
4# Linux
5dpkg -l | grep -E "(libpango|gcc|ghostscript|zint)"
6
7# Verify Python installation
8python3 --version
9which python3
10
11# Check pip installation
12pip3 --version
13pip3 list | grep karrio

Database Connection Issues

Test database connection
1karrio dbshell
2
3# Check database settings
4karrio shell -c "from django.conf import settings; print(settings.DATABASES)"

Redis Connection Issues

Test Redis connection
1karrio shell -c "import redis; r = redis.Redis(host='localhost', port=6379); print(r.ping())"

Server Startup Issues

Check for port conflicts
1netstat -tuln | grep :5002
2
3# Verify environment variables
4karrio shell -c "from django.conf import settings; print(settings.SECRET_KEY[:10])"
5
6# Test server configuration
7karrio check

Worker Issues

Check worker status
1karrio run_huey --help
2
3# Test task queue
4karrio shell -c "from huey.contrib.djhuey import get_queue; print(get_queue())"

Performance Optimization

For production environments:

Adjust worker processes based on CPU cores
1export KARRIO_WORKERS=4
2export BACKGROUND_WORKERS=4
3
4# Monitor resource usage
5htop
6iostat -x 1

Support

For issues specific to server installation:

  • Check the troubleshooting section above
  • Review system logs for error messages
  • Ensure all dependencies are properly installed
  • Verify database and Redis connectivity

For general Karrio support, refer to the main documentation or GitHub issues.