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

Self-Hosting

There are multiple ways to deploy Karrio, providing support for customers who want to implement their shipping API infrastructure within their existing tech stack. This guide will help you get started with self-hosting Karrio.

Requirements

Karrio runs with minimal hardware requirements. The most resource-intensive operations are during initial setup and database migrations, but once running, it’s relatively lightweight.

Hardware Requirements

  • Minimal Setup:

    • 2GB RAM
    • 1 CPU core
    • 10GB storage

  • Recommended Setup (Production):

    • 4GB+ RAM
    • 2+ CPU cores
    • 20GB+ storage

Software Requirements

  • Operating System:

    • Karrio works well on Linux, macOS, and Windows
    • For production deployments, we recommend Linux (Ubuntu 20.04+ or Debian 11+)

  • Required Software:

    • Docker and Docker Compose (for container-based deployments)
    • Git (for source-based deployments)
    • PostgreSQL 12+ (if not using containerized database)
    • Redis (if not using containerized cache)

Why Self-Host?

Self-hosting Karrio offers several advantages:

  • Data Control: Keep all your shipping data within your own infrastructure
  • Customization: Modify the platform to suit your specific needs
  • Integration: Seamlessly integrate with your existing systems
  • Cost: Potentially reduce costs for high-volume shipping operations
  • Compliance: Meet specific regulatory or security requirements

Deployment Options

Docker

Docker is the recommended and easiest way to get started with self-hosting Karrio. It provides a consistent environment across different platforms and simplifies the setup process.

For quick deployments, we offer a one-click installation script:

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

Cloud Providers

Deploy Karrio on popular cloud platforms with detailed guides:

Environment Configuration

Karrio is configured primarily through environment variables. The most important ones are:

  • SECRET_KEY: A secret key used for security
  • DOMAIN: Your domain name (for production)
  • DASHBOARD_URL: URL for the dashboard interface
  • KARRIO_PUBLIC_URL: URL for the API
  • DATABASE_*: Database connection details
  • REDIS_*: Redis connection details

For a comprehensive list, see the Environment Variables documentation.

Initial Setup

After deployment, you can access your Karrio instance:

  • Dashboard: Default at http://localhost:3000 or your configured domain
  • API: Default at http://localhost:5002 or your configured domain

Default login credentials:

  • Email: admin@example.com
  • Password: demo

For production environments, we strongly recommend changing these credentials immediately.

Integration with Shipping Carriers

Karrio supports multiple shipping carriers out of the box. To use them, you’ll need to configure credentials in your environment variables:

  • USPS
  • UPS
  • FedEx
  • DHL
  • And many more

Each carrier requires specific API credentials that you can obtain from your carrier account.

Maintenance

Backups

It’s important to regularly back up your Karrio data:

Backup PostgreSQL database
1docker-compose exec db pg_dump -U postgres -d db > karrio_backup_$(date +%Y%m%d).sql
2
3# Backup configuration
4cp .env .env.backup.$(date +%Y%m%d)

Upgrades

To upgrade your Karrio instance, we provide an upgrade script for hobby deployments:

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

For manual deployments, see our Upgrade Guide.

Next Steps

  1. Choose your preferred deployment method
  2. Set up your environment variables
  3. Learn how to upgrade your installation
  4. Explore carrier configurations

Support

If you need help with your self-hosted Karrio instance: