GCP Deployment

This guide will walk you through deploying Karrio on Google Cloud Platform (GCP).

Prerequisites

A Google Cloud Platform account
GCP project with billing enabled
Basic knowledge of GCP, Docker, and Docker Compose

Step 1: Create a Compute Engine VM Instance

Log into the Google Cloud Console
Navigate to “Compute Engine” > “VM Instances”
Click “Create Instance”
Configure your instance:
- Name: karrio-server
- Region/Zone: Choose a region close to your users
- Machine Type:
  - For production: At least e2-medium (2 vCPU, 4 GB RAM)
  - For development/testing: e2-small (2 vCPU, 2 GB RAM)
- Boot Disk:
  - OS: Ubuntu 22.04 LTS
  - Size: At least 20 GB SSD Persistent Disk
- Firewall:
  - Allow HTTP traffic
  - Allow HTTPS traffic
Advanced options:
- Networking > Network Interfaces:
  - Configure network tags for firewall rules
Click “Create”

Step 2: Set Up Firewall Rules

Ensure you have the following firewall rules:

Navigate to “VPC Network” > “Firewall”
Create or verify rules for:
- Allow HTTP (port 80)
- Allow HTTPS (port 443)
- Allow SSH (port 22)

Step 3: Connect to Your VM

Connect to your VM instance using SSH:

1gcloud compute ssh karrio-server --zone=your-zone

Alternatively, you can use the SSH button in the Google Cloud Console.

Step 4: Install Docker and Docker Compose

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# Verify installations
23docker --version
24docker-compose --version
25
26# Log out and log back in for group changes to take effect
27exit

Step 5: Deploy Karrio

Reconnect to your VM 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 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 6: Set Up a Static External IP

To ensure your Karrio instance remains accessible with the same IP:

In the Google Cloud Console, navigate to “VPC Network” > “External IP addresses”
Click “Reserve Static Address”
Configure the static IP:
- Name: karrio-static-ip
- Network Service Tier: Premium
- IP Version: IPv4
- Type: Regional
- Region: Same as your VM
- Attached To: Your VM instance
Click “Reserve”

Step 7: Configure DNS

In your domain registrar or DNS provider, add the following records:
- Type: A, Name: api, Value: Your VM’s static IP
- Type: A, Name: app, Value: Your VM’s static IP
Wait for DNS propagation (can take up to 24-48 hours, but often much quicker)

Step 8: 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 a Load Balancer (Optional)

For high-availability deployments:

In the Google Cloud Console, navigate to “Network Services” > “Load Balancing”
Click “Create Load Balancer”
Choose “HTTP(S) Load Balancing”
Configure your load balancer:
- Backend configuration: Create a backend service pointing to your VM
- Frontend configuration: Set up HTTPS with your SSL certificates
Update your DNS records to point to the load balancer’s IP address

Backup and Restore

Setting Up Automated Backups

Create a simple backup script:

1cat > ~/backup_karrio.sh << 'EOL'
2#!/bin/bash
3TIMESTAMP=$(date +%Y%m%d_%H%M%S)
4BACKUP_DIR=~/karrio-backups
5mkdir -p $BACKUP_DIR
6
7# Backup database
8cd ~/karrio
9docker-compose exec -T db pg_dump -U postgres -d db > $BACKUP_DIR/karrio_db_$TIMESTAMP.sql
10
11# Backup configuration files
12cp ~/karrio/.env $BACKUP_DIR/env_$TIMESTAMP
13cp ~/karrio/Caddyfile $BACKUP_DIR/Caddyfile_$TIMESTAMP
14
15# Upload to Google Cloud Storage (optional)
16# gsutil cp $BACKUP_DIR/karrio_db_$TIMESTAMP.sql gs://your-bucket/karrio-backups/
17# gsutil cp $BACKUP_DIR/env_$TIMESTAMP gs://your-bucket/karrio-backups/
18# gsutil cp $BACKUP_DIR/Caddyfile_$TIMESTAMP gs://your-bucket/karrio-backups/
19EOL
20
21chmod +x ~/backup_karrio.sh

Schedule the backup script with cron:

1(crontab -l 2>/dev/null; echo "0 2 * * * ~/backup_karrio.sh") | crontab -

Setting Up Google Cloud Storage for Backups (Optional)

Create a Storage Bucket:
- In the Google Cloud Console, navigate to “Storage” > “Browser”
- Click “Create Bucket”
- Name your bucket (e.g., karrio-backups-YOUR-PROJECT)
- Configure other settings as needed
- Click “Create”
Install gsutil (if not already installed):

1sudo apt-get install -y google-cloud-sdk-gsutil

Uncomment the gsutil commands in the backup script to enable cloud storage backups

Monitoring

For basic monitoring, you can use:

Google Cloud Monitoring
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 firewall rules
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 VM is running out of resources:

Check resource usage:
```
1top
```
Consider upgrading to a larger machine type:
- Stop your VM in the Google Cloud Console
- Edit the machine type
- Restart your VM

Optimizing Costs

To optimize your GCP costs:

Use Compute Engine sustained use discounts (automatic)
Consider using preemptible VMs for non-production environments
Right-size your VM instance based on actual usage
Set up budget alerts in the Google Cloud Console

Getting Started

Deployments

Guides