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

Digital Ocean

Deploy Karrio on Digital Ocean.

Prerequisites

  • Digital Ocean account
  • Basic knowledge of Docker and Docker Compose

Step 1: Create a Droplet

  1. Log into Digital Ocean account
  2. Navigate to “Droplets” section
  3. Click “Create Droplet”
  4. Choose image:
    • Marketplace tab → Docker (pre-configured), or
    • Ubuntu 22.04 LTS (clean installation)
  5. Select plan:
    • Production: Standard Droplet with 2 GB RAM / 1 CPU
    • Development: Basic Droplet with 2 GB RAM / 1 CPU
  6. Choose datacenter region
  7. Add SSH keys or password authentication
  8. Choose hostname (e.g., karrio-server)
  9. Click “Create Droplet”

Step 2: Set Up DNS Records

  1. Go to “Networking” > “Domains”
  2. Add existing domain or purchase one
  3. Create DNS records:
    • Type: A, Hostname: api, Value: Your Droplet’s IP
    • Type: A, Hostname: app, Value: Your Droplet’s IP

Step 3: Connect to Your Droplet

1ssh root@your-droplet-ip

Or with SSH key:

1ssh -i /path/to/your-key username@your-droplet-ip

Step 4: Install Docker and Docker Compose

Skip if you used Docker Marketplace image.

1sudo apt update && sudo apt upgrade -y
2sudo apt install -y apt-transport-https ca-certificates curl software-properties-common
3curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
4sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"
5sudo apt update
6sudo apt install -y docker-ce
7sudo systemctl enable docker
8sudo systemctl start docker
9sudo usermod -aG docker $USER
10sudo curl -L "https://github.com/docker/compose/releases/download/v2.18.1/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
11sudo chmod +x /usr/local/bin/docker-compose
12exit

Verify after logging back in:

1docker --version
2docker-compose --version

Step 5: Configure Firewall

  1. Go to “Networking” > “Firewalls”
  2. Click “Create Firewall”
  3. Name: karrio-firewall
  4. Configure inbound rules:
    • Allow SSH (port 22)
    • Allow HTTP (port 80)
    • Allow HTTPS (port 443)
  5. Apply to your Karrio Droplet
  6. Click “Create Firewall”

Step 6: Deploy Karrio

Option 1: One-Click Hobby Deployment

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

When prompted, enter your domain name.

Option 2: Manual Deployment

1mkdir -p ~/karrio
2cd ~/karrio
3curl -O https://raw.githubusercontent.com/karrioapi/karrio/HEAD/docker/docker-compose.yml
4curl -O https://raw.githubusercontent.com/karrioapi/karrio/HEAD/docker/.env
5docker-compose up -d

Edit .env with your configuration. Set up your preferred webserver for HTTPS and domain routing.

Step 7: Access Your Karrio Instance

  • Dashboard: https://app.your-domain.com
  • API: https://api.your-domain.com

Default login: admin@example.com / demo

Creating a Floating IP (Recommended)

  1. Go to “Networking” > “Floating IPs”
  2. Click “Assign Floating IP”
  3. Select your Karrio Droplet
  4. Click “Assign Floating IP”

Update DNS records to point to this Floating IP.

Setting Up a Load Balancer (Optional)

  1. Go to “Networking” > “Load Balancers”
  2. Click “Create Load Balancer”
  3. Configure:
    • Region: Same as your Droplet
    • Forwarding Rules: HTTP on port 80, HTTPS on port 443
    • Health Checks: HTTP on port 80
  4. Select your Droplet
  5. Click “Create Load Balancer”

Update DNS records to point to the load balancer’s IP address.

Backup and Restore

Automated Backups

  1. Go to your Droplet’s page
  2. Click “Backups” in the left sidebar
  3. Click “Enable Backups”

Creates weekly backups of your entire Droplet.

Manual Database Backup

1cd ~/karrio
2docker-compose exec db pg_dump -U postgres -d db > karrio_backup_$(date +%Y%m%d).sql

Digital Ocean Spaces (Optional)

  1. Create a Space in Digital Ocean control panel
  2. Install s3cmd: sudo apt install -y s3cmd
  3. Configure: s3cmd --configure
  4. Upload: s3cmd put karrio_backup_$(date +%Y%m%d).sql s3://your-space-name/

Monitoring

  • Digital Ocean’s built-in Droplet monitoring
  • Container logs: cd ~/karrio && docker-compose logs -f
  • Digital Ocean monitoring agent
  • Built-in alerts for CPU, memory, and disk usage

Updating

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

Scaling Your Deployment

Vertical Scaling:

  1. Power off your Droplet
  2. Select “Resize Droplet” from control panel
  3. Choose a larger plan
  4. Power on your Droplet

Horizontal Scaling:

  • Create multiple Droplets
  • Set up a Load Balancer
  • Configure managed database (Digital Ocean Managed PostgreSQL)

Troubleshooting

SSL Certificate Issues

1cd ~/karrio
2docker-compose logs caddy

Check: DNS records, ports 80/443 open in firewall

Container Issues

1cd ~/karrio
2docker-compose ps
3docker-compose logs <service_name>

Resource Limitations

Monitor usage on Digital Ocean dashboard. Upgrade Droplet size if consistently using >70% of CPU or memory.