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

AWS Deployment

This guide will walk you through deploying Karrio on Amazon Web Services (AWS).

Prerequisites

  1. An active AWS account
  2. Familiarity with AWS services and management console
  3. Basic knowledge of Docker and Docker Compose

Step 1: Create an EC2 Instance

  1. Log into the AWS Management Console
  2. Navigate to EC2 service
  3. Click “Launch Instance”
  4. Choose an Amazon Machine Image (AMI):
    • We recommend using Amazon Linux 2023 or Ubuntu 22.04 LTS
  5. Select an instance type:
    • For production: At least t3.medium (2 vCPU, 4 GB RAM)
    • For development/testing: t3.small (2 vCPU, 2 GB RAM)
  6. Configure instance details:
    • Default settings should work for most deployments
    • Ensure the instance is in your preferred VPC
  7. Add storage:
    • Allocate at least 20 GB of EBS storage
  8. Add tags (optional):
    • Key: Name, Value: karrio-server
  9. Configure security group:
    • Allow HTTP (port 80)
    • Allow HTTPS (port 443)
    • Allow SSH (port 22) from your IP address only
  10. Review and launch the instance
  11. Create or select an existing key pair for SSH access

Step 2: Connect to Your Instance

Once your instance is running, connect to it using SSH:

1ssh -i /path/to/your-key.pem ec2-user@your-instance-public-ip

For Ubuntu:

1ssh -i /path/to/your-key.pem ubuntu@your-instance-public-ip

Step 3: Install Docker and Docker Compose

For Amazon Linux 2023:

Update system packages
1sudo yum update -y
2
3# Install Docker
4sudo yum install -y docker
5sudo systemctl enable docker
6sudo systemctl start docker
7sudo usermod -aG docker $USER
8
9# Install Docker Compose
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
12
13# Verify installations
14docker --version
15docker-compose --version
16
17# Log out and log back in for group changes to take effect
18exit

For Ubuntu:

Update system packages
1sudo apt update
2sudo apt upgrade -y
3
4# Install prerequisites
5sudo apt install -y apt-transport-https ca-certificates curl software-properties-common
6
7# Add Docker repository
8curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
9sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"
10
11# Install Docker
12sudo apt update
13sudo apt install -y docker-ce
14sudo systemctl enable docker
15sudo systemctl start docker
16sudo usermod -aG docker $USER
17
18# Install Docker Compose
19sudo curl -L "https://github.com/docker/compose/releases/download/v2.18.1/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
20sudo chmod +x /usr/local/bin/docker-compose
21
22# Log out and log back in for group changes to take effect
23exit

Step 4: Deploy Karrio

  1. Reconnect to your instance after logging out
  2. Deploy Karrio using one of the following methods:

Option 1: One-Click Hobby Deployment

This is the simplest method for a quick setup:

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

When prompted, enter your domain name (e.g., karrio.yourdomain.com).

Option 2: Manual Deployment

For more control over the deployment:

Create a directory for Karrio
1mkdir -p ~/karrio
2cd ~/karrio
3
4# Download the docker-compose file
5curl -O https://raw.githubusercontent.com/karrioapi/karrio/HEAD/docker/docker-compose.hobby.yml
6mv docker-compose.hobby.yml docker-compose.yml
7
8# Create the .env file
9cat > .env << EOL
10# Database settings
11DATABASE_ENGINE=postgresql_psycopg2
12DATABASE_NAME=db
13DATABASE_USERNAME=postgres
14DATABASE_PASSWORD=postgres
15DATABASE_HOST=db
16DATABASE_PORT=5432
17
18# Redis settings
19REDIS_HOST=redis
20REDIS_PORT=6379
21
22# Karrio settings
23SECRET_KEY=$(openssl rand -base64 32)
24JWT_SECRET=$(openssl rand -base64 32)
25KARRIO_TAG=latest
26
27# Domain settings
28DOMAIN=your-domain.com
29DASHBOARD_URL=https://app.your-domain.com
30KARRIO_PUBLIC_URL=https://api.your-domain.com
31EOL
32
33# Create the Caddyfile for reverse proxy
34cat > Caddyfile << EOL
35{
36  email your-email@example.com
37}
38
39api.your-domain.com {
40  reverse_proxy karrio.api:5002
41}
42
43app.your-domain.com {
44  reverse_proxy karrio.dashboard:3000
45}
46EOL
47
48# Start the containers
49docker-compose up -d

Remember to replace your-domain.com, app.your-domain.com, api.your-domain.com, and your-email@example.com with your actual domain and email details.

Step 5: Configure DNS

  1. In your domain registrar or DNS provider, add the following records:

    • Type: A, Name: api, Value: Your EC2 instance’s public IP
    • Type: A, Name: app, Value: Your EC2 instance’s public IP

  2. Wait for DNS propagation (can take up to 24-48 hours, but often much quicker)

Step 6: Access Your Karrio Instance

After DNS propagation:

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

Default login credentials: admin@example.com / demo

Setting Up an Elastic IP (Recommended)

To ensure your Karrio instance remains accessible even after instance restarts:

  1. In the AWS console, navigate to EC2 > Elastic IPs
  2. Click “Allocate Elastic IP address”
  3. Select “Amazon’s pool of IPv4 addresses”
  4. Click “Allocate”
  5. Select the new Elastic IP, click “Actions” > “Associate Elastic IP address”
  6. Select your Karrio instance
  7. Click “Associate”

Update your DNS records to point to this Elastic IP.

Setting Up a Load Balancer (Optional)

For high-availability deployments:

  1. Create an Application Load Balancer
  2. Configure HTTPS listeners (port 443)
  3. Set up target groups pointing to your EC2 instance(s)
  4. Update your DNS records to point to the load balancer’s DNS name

Backup and Restore

Setting Up AWS Backup

  1. Navigate to AWS Backup in the console
  2. Create a backup plan with your preferred schedule
  3. Assign your EC2 instance and EBS volume to the backup plan

Manual Database Backup

To manually back up your Karrio database:

1cd ~/karrio
2docker-compose exec db pg_dump -U postgres -d db > karrio_backup_$(date +%Y%m%d).sql
3aws s3 cp karrio_backup_$(date +%Y%m%d).sql s3://your-backup-bucket/

Monitoring

For basic monitoring, you can use:

  1. AWS CloudWatch for instance metrics
  2. Container logs: 
    1cd ~/karrio
2docker-compose logs -f

Updating Karrio

To update your Karrio instance:

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

Troubleshooting

SSL Certificate Issues

If SSL certificates aren’t being issued:

  1. Check that your DNS records are correctly set up
  2. Verify that ports 80 and 443 are open in your security group
  3. Check the Caddy logs: 
    1cd ~/karrio
2docker-compose logs caddy

Container Issues

If containers aren’t starting properly:

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

Instance Resources

If your instance is running out of resources:

  1. Check usage with top or htop
  2. Consider upgrading to a larger instance type through the AWS console