📖 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

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