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 securityDOMAIN
: Your domain name (for production)DASHBOARD_URL
: URL for the dashboard interfaceKARRIO_PUBLIC_URL
: URL for the APIDATABASE_*
: Database connection detailsREDIS_*
: 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 database1docker-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
- Choose your preferred deployment method
- Set up your environment variables
- Learn how to upgrade your installation
- Explore carrier configurations
Support
If you need help with your self-hosted Karrio instance:
- Join our Community Forum
- Consider our Enterprise Support Plans for priority assistance