Local Development

Copy for LLM

Welcome to the Karrio development guide! This resource covers the classic localhost workflow and the optional HTTPS proxy powered by Caddy. Whether you’re adding a new carrier integration, enhancing the API, or improving the dashboard, this guide walks you through the tooling that keeps local feedback fast.

Architecture Overview

Karrio is built with a flexible architecture consisting of several components:

• API Server: Django REST Framework application that provides the core API
• Dashboard: Next.js application for the user interface
• Docs: Next.js site for documentation and marketing pages
• Worker: Huey workers for background tasks
• Database: PostgreSQL for data storage (SQLite supported for development)
• Cache: Redis for caching and as a message broker
• Maildev: Local SMTP sink used during development
• Caddy (optional): HTTPS proxy for api.karrio.local, app.karrio.local, karrio.local

Prerequisites

Before you begin, make sure you have the following installed:

• Git
• Node.js v18+ and npm v10+
• Python 3.12+
• Docker & Docker Compose (optional, for Docker-based setup)

Quick Start (Dockerless)

1git clone https://github.com/[YOUR_USERNAME]/karrio.git
2cd karrio
3
4# Optional: install native dependencies (mkcert, caddy, libffi, zint, …)
5./bin/install-binaries
6
7# Provision Python, Node, certificates, env files (safe to rerun)
8./bin/install-dev
9
10# Launch API + Dashboard + Docs + Maildev (localhost by default)
11./bin/dev up

./bin/install-dev ensures that pyenv/nvm are present, installs the supported Python and Node.js versions, installs repo dependencies, generates mkcert certificates under .karrio/certs, copies default .env files, and prints a summary with the relevant URLs. The env files keep http://localhost:* defaults; HTTPS is opt-in via the --with-https flag on ./bin/dev up.

Add these entries to /etc/hosts so browsers resolve the local HTTPS domains:

127.0.0.1 api.karrio.local app.karrio.local karrio.local

If Caddy cannot bind to ports 80/443 on Linux, grant the binary privileged-port access once:

1sudo setcap "cap_net_bind_service=+ep" $(command -v caddy)

Advanced: run the proxy manually (normally ./bin/dev up --with-https handles this):

1CADDY_CERT_DIR="$(pwd)/.karrio/certs" caddy run --config docker/Caddyfile.dev

./bin/dev up accepts component names so you can launch only what you need. Add --with-https to enable the HTTPS proxy when desired:

1./bin/dev up api                 # API + Maildev (localhost)
2./bin/dev up dashboard           # Dashboard (localhost)
3./bin/dev up docs                # Docs (localhost)
4./bin/dev up api dashboard       # Mix and match (localhost)
5./bin/dev up --with-https api    # Same, but with Caddy + HTTPS

HTTPS is off by default. To force-disable HTTPS in any context:

1SKIP_CADDY=true ./bin/dev up

When you launch with --with-https, the script exports:

1export KARRIO_URL=https://api.karrio.local
2export KARRIO_PUBLIC_URL=https://api.karrio.local
3export NEXT_PUBLIC_KARRIO_PUBLIC_URL=https://api.karrio.local
4export NEXTAUTH_URL=https://app.karrio.local

If Caddy isn’t available the script keeps the http://localhost:* values. Update those variables (or the values in apps/dashboard/.env) if you need to point the UI at another API.

Service	HTTP	HTTPS (requires Caddy)
API	http://localhost:5002	https://api.karrio.local
Dashboard	http://localhost:3002	https://app.karrio.local
Docs	http://localhost:3005	https://karrio.local
Maildev	http://localhost:1080	–

./bin/dev up also exports NODE_EXTRA_CA_CERTS to the mkcert root so the Next.js servers trust the HTTPS endpoints automatically.

Stopping services

To stop all development services started by ./bin/dev up:

1./bin/dev down

If you started with --no-wait, you can stop later with the same ./bin/dev down command.

Classic Manual Setup (reference)

If you want the manual steps, the original workflow remains available.

1. Clone the Repository

1git clone https://github.com/[YOUR_USERNAME]/karrio.git
2cd karrio

2. Install System Dependencies

1./bin/install-binaries

This installs system dependencies based on your OS:

• macOS: gcc, pango, libffi, ghostscript, zint, caddy, mkcert
• Linux: libpango1.0-0, libpangoft2-1.0-0, gcc, ghostscript, zint, caddy, mkcert

If you encounter permission issues:

1chmod +x ./bin/*

3. Set up Python Environment manually

1source ./bin/setup-server-env

4. Apply Database Migrations

1karrio migrate

Using PostgreSQL Instead

Update your .env accordingly and start the PostgreSQL container with docker compose -f docker/docker-compose.yml up -d db.

5. Collect Static Assets

1karrio collectstatic --noinput

6. Create Admin User

1karrio createsuperuser

7. Start the Server

1karrio runserver

8. Start the Dashboard manually

1npm i
2npm run dev -w @karrio/dashboard

Working on the Server

1source bin/activate-env
2karrio migrate
3karrio createsuperuser
4karrio collectstatic --noinput
5./bin/run-server-tests

Database Management

Reset
1docker compose -f docker/docker-compose.yml down
2docker compose -f docker/docker-compose.yml up -d db
3
4# Backup
5karrio dumpdata --natural-foreign --natural-primary -o ../backup/data.json
6
7# Restore
8karrio loaddata ../backup/data.json

Code Organization

• apps/: API, dashboard, docs, marketing
• modules/: shared python packages (core, connectors, automation, …)
• bin/: helper scripts for development, testing, deployment
• docker/: docker-compose manifests and container assets
• schemas/: API schema definitions
• ee/: enterprise-specific code (when applicable)

Adding a New Carrier

1. Create a new module under modules/connectors.
2. Implement the carrier interfaces (CarrierInterface, ShippingInterface, etc.).
3. Add configuration and validation.
4. Write tests and update documentation.

See Adding a New Carrier for the full walkthrough.

Troubleshooting

• Caddy fails to start – ensure ports 80/443 are free and run sudo setcap "cap_net_bind_service=+ep" $(command -v caddy). Check /tmp/caddy-dev.log for details.
• Certificates not trusted – rerun ./bin/install-dev so mkcert reinstalls the local CA. Restart your browser afterwards.
• Dashboard cannot reach API – verify the API component is running or set KARRIO_URL to a remote endpoint before launching the dashboard.
• Node or Python version warnings – the setup script skips unsupported versions. Upgrade manually and rerun the script.

Docker-based Development (Alternative)

Use the helper script to create and manage the dev container defined in the root docker-compose.yml:

Create and initialize the dev container
1./bin/docker-env create
2
3# Open a shell in the dev container
4./bin/docker-env shell

Start services inside the container (in separate terminals):

API (terminal 1)
1docker compose exec -it karriodev bash -lc 'source bin/activate-env; karrio runserver'
2
3# Dashboard (terminal 2)
4docker compose exec -it karriodev bash -lc 'npm run dev -w @karrio/dashboard'
5
6# Docs (optional, terminal 3)
7docker compose exec -it karriodev bash -lc 'npm run dev:web -w @karrio/web'

Optional HTTPS proxy (Caddy) from the host:

1docker compose up -d caddy

Stop or remove the dev container:

1./bin/docker-env off       # stop
2./bin/docker-env destroy   # remove

Refer to Self-hosting Environment Variables for tuning port mappings and credentials.