AWS Deployment
This guide will walk you through deploying Karrio on Amazon Web Services (AWS).
Prerequisites
- An active AWS account
- Familiarity with AWS services and management console
- Basic knowledge of Docker and Docker Compose
Step 1: Create an EC2 Instance
- Log into the AWS Management Console
- Navigate to EC2 service
- Click “Launch Instance”
- Choose an Amazon Machine Image (AMI):
- We recommend using Amazon Linux 2023 or Ubuntu 22.04 LTS
- 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)
- Configure instance details:
- Default settings should work for most deployments
- Ensure the instance is in your preferred VPC
- Add storage:
- Allocate at least 20 GB of EBS storage
- Add tags (optional):
- Key:
Name
, Value:karrio-server
- Key:
- Configure security group:
- Allow HTTP (port 80)
- Allow HTTPS (port 443)
- Allow SSH (port 22) from your IP address only
- Review and launch the instance
- 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 packages1sudo 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 packages1sudo 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
- Reconnect to your instance after logging out
- 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 Karrio1mkdir -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
-
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
- Type:
-
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:
- In the AWS console, navigate to EC2 > Elastic IPs
- Click “Allocate Elastic IP address”
- Select “Amazon’s pool of IPv4 addresses”
- Click “Allocate”
- Select the new Elastic IP, click “Actions” > “Associate Elastic IP address”
- Select your Karrio instance
- Click “Associate”
Update your DNS records to point to this Elastic IP.
Setting Up a Load Balancer (Optional)
For high-availability deployments:
- Create an Application Load Balancer
- Configure HTTPS listeners (port 443)
- Set up target groups pointing to your EC2 instance(s)
- Update your DNS records to point to the load balancer’s DNS name
Backup and Restore
Setting Up AWS Backup
- Navigate to AWS Backup in the console
- Create a backup plan with your preferred schedule
- 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:
- AWS CloudWatch for instance metrics
- 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:
- Check that your DNS records are correctly set up
- Verify that ports 80 and 443 are open in your security group
- 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:
- Check usage with
top
orhtop
- Consider upgrading to a larger instance type through the AWS console