Deploy InsForge to Google Cloud Compute Engine

This guide will walk you through deploying InsForge on Google Cloud Compute Engine using Docker Compose.

This cloud walkthrough is community-maintained and can lag the latest InsForge release. The canonical, always-current setup is the deploy/docker-compose/ directory in the InsForge repo.

📋 Prerequisites

Google Cloud Account with billing enabled
Basic knowledge of SSH and command-line operations
Domain name (optional, for custom domain setup)

🚀 Deployment Steps

1. Create and Configure Compute Engine Instance

1.1 Create Google Cloud Project

Log into Google Cloud Console at console.cloud.google.com
Click “Select a project” in the top navigation bar
Click “New Project”
Enter project name (e.g., insforge-deployment)
Click “Create”
Wait for project creation to complete

1.2 Enable Required APIs

In your project, navigate to APIs & Services → Library
Search for and enable these APIs:
- Compute Engine API
- Cloud Storage API (if using for backups)
- Cloud SQL Admin API (if using Cloud SQL)

1.3 Create Compute Engine Instance

Navigate to Compute Engine → VM instances
Click “Create Instance”
Configure your instance:
- Name: insforge-server (or your preferred name)
- Region: Choose a region close to your users
- Zone: Select an availability zone (e.g., us-central1-a)
- Machine configuration:
  - Series: N2 or E2
  - Machine type: e2-medium or larger (minimum 2 vCPU, 4 GB RAM)
    - For production: e2-standard-2 (2 vCPU, 8 GB RAM) recommended
    - For testing: e2-small (2 vCPU, 2 GB RAM) minimum
- Boot disk:
  - Operating system: Ubuntu LTS (Ubuntu 22.04 LTS or newer)
  - Boot disk type: Balanced persistent disk
  - Size: 30 GB (minimum 20 GB recommended)
- Firewall:
  - Allow HTTP traffic: Checked
  - Allow HTTPS traffic: Checked

1.4 Configure Firewall Rules

Navigate to VPC network → Firewall
Create or modify firewall rules to allow the following ports:

Name	Direction	Targets	Protocols/ports	Source filters
insforge-ssh	Ingress	insforge-server	tcp:22	Your IP address
insforge-http	Ingress	insforge-server	tcp:80	0.0.0.0/0
insforge-https	Ingress	insforge-server	tcp:443	0.0.0.0/0
insforge-app	Ingress	insforge-server	tcp:7130	0.0.0.0/0
insforge-deno	Ingress	insforge-server	tcp:7133	0.0.0.0/0
insforge-postgrest	Ingress	insforge-server	tcp:5430	0.0.0.0/0
insforge-postgres	Ingress	insforge-server	tcp:5432	0.0.0.0/0 (only if needed externally)

⚠️ Security Note: For production, restrict PostgreSQL (5432) to specific IP addresses or remove external access entirely. Consider using a reverse proxy (nginx) and exposing only ports 80/443.

2. Connect to Your Compute Engine Instance

In the Google Cloud Console, go to Compute Engine → VM instances
Find your instance and click the SSH button in the same row, or:

# Use gcloud CLI to SSH (if you have gcloud SDK installed locally)
gcloud compute ssh insforge-server --zone=your-zone

3. Install Dependencies

3.1 Update System Packages

sudo apt update && sudo apt upgrade -y

3.2 Install Docker

# Add Docker's official GPG key
sudo apt-get update
sudo apt-get install ca-certificates curl gnupg
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

# Add Docker repository
echo \
  "deb [arch="$(dpkg --print-architecture)" signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  "$(. /etc/os-release && echo "$VERSION_CODENAME")" stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Install Docker
sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

3.3 Add Your User to Docker Group

After installing Docker, you need to add your user to the docker group to run Docker commands without sudo:

# Add your user to the docker group
sudo usermod -aG docker $USER

# Apply the group changes
newgrp docker

Verify it works:

# This should now work without sudo
docker ps

💡 Note: If docker ps doesn’t work immediately, log out and log back in via SSH, then try again.

⚠️ Security Note: Adding a user to the docker group grants them root-equivalent privileges on the system. This is acceptable for single-user environments like your Compute Engine instance, but be cautious on shared systems.

3.4 Install Git

sudo apt install git -y

4. Deploy InsForge

4.1 Clone Repository

cd ~
git clone https://github.com/insforge/insforge.git
cd insforge/deploy/docker-compose

4.2 Create Environment Configuration

Create your .env file with production settings:

nano .env

The repo ships a template at deploy/docker-compose/.env.example. Copy it and edit the values:

cp .env.example .env
nano .env

At a minimum, set these values:

# Authentication (required)
# IMPORTANT: Generate a strong random secret for production (32+ characters)
JWT_SECRET=your-secret-key-here-must-be-32-char-or-above

# Admin account (used for initial setup)
ADMIN_EMAIL=admin@example.com
ADMIN_PASSWORD=change-this-password

# Database (required)
POSTGRES_PASSWORD=your-secure-postgres-password

Optional values you may want to set:

# Encryption key for secrets and database encryption.
# Falls back to JWT_SECRET if left empty.
ENCRYPTION_KEY=

# AI/LLM (get a key from https://openrouter.ai/keys)
OPENROUTER_API_KEY=

# Site deployments and custom domains
VERCEL_TOKEN=
VERCEL_TEAM_ID=
VERCEL_PROJECT_ID=

# OAuth providers (Google, GitHub, etc.)
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=
GITHUB_CLIENT_ID=
GITHUB_CLIENT_SECRET=

See deploy/docker-compose/.env.example for the full list of supported variables. Generate Secure Secrets:

# Generate JWT_SECRET (32+ characters)
openssl rand -base64 32

# Generate ENCRYPTION_KEY (32 characters)
openssl rand -base64 24

💡 Important: Save these secrets securely. You’ll need them if you ever migrate or restore your instance.

4.3 Start InsForge Services

# Pull Docker images and start services
docker compose up -d

# View logs to ensure everything started correctly
docker compose logs -f

Press Ctrl+C to exit log view.

4.4 Verify Services

# Check running containers
docker compose ps

# You should see 4 running services:
# - postgres
# - postgrest
# - insforge
# - deno

5. Access Your InsForge Instance

5.1 Test Backend API

curl http://your-external-ip:7130/api/health

Expected response:

{
  "status": "ok",
  "version": "2.1.7",
  "service": "Insforge OSS Backend",
  "timestamp": "2025-10-17T..."
}

5.2 Access Dashboard

Open your browser and navigate to:

http://your-external-ip:7130

6. Configure Domain (Optional but Recommended)

6.1 Reserve a Static External IP

In Google Cloud Console, go to VPC network → External IP addresses
Click Reserve Static Address
Name: insforge-ip
Type: Regional or Global (Regional for VM instances)
Region: Same as your VM instance
Click Reserve

6.2 Update DNS Records

Point your domain’s DNS records to the reserved static IP:

api.yourdomain.com    → your-static-external-ip
app.yourdomain.com    → your-static-external-ip

6.3 Install Nginx Reverse Proxy

sudo apt install nginx -y

Create Nginx configuration:

sudo nano /etc/nginx/sites-available/insforge

Add the following configuration:

# Backend API
server {
    listen 80;
    server_name api.yourdomain.com;

    location / {
        proxy_pass http://localhost:7130;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
    }
}

# Dashboard
server {
    listen 80;
    server_name app.yourdomain.com;

    location / {
        proxy_pass http://localhost:7130;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
    }
}

Enable the configuration:

sudo ln -s /etc/nginx/sites-available/insforge /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

6.4 Install SSL Certificate (Recommended)

# Install Certbot
sudo apt install certbot python3-certbot-nginx -y

# Obtain SSL certificates
sudo certbot --nginx -d api.yourdomain.com -d app.yourdomain.com

# Follow the prompts to complete setup

Update your .env file with HTTPS URLs:

cd ~/insforge/deploy/docker-compose
nano .env

Change:

API_BASE_URL=https://api.yourdomain.com
VITE_API_BASE_URL=https://api.yourdomain.com

Restart services:

docker compose down
docker compose up -d

🔧 Management & Maintenance

View Logs

# All services
docker compose logs -f

# Specific service
docker compose logs -f insforge
docker compose logs -f postgres
docker compose logs -f deno

Stop Services

docker compose down

Restart Services

docker compose restart

Update InsForge

cd ~/insforge/deploy/docker-compose
git pull origin main
docker compose pull && docker compose up -d

Backup Database

# Create backup (run from deploy/docker-compose/)
docker compose exec postgres pg_dump -U postgres insforge > backup_$(date +%Y%m%d_%H%M%S).sql

# Store backup in Google Cloud Storage (optional)
# First, install Google Cloud CLI and authenticate
# Then:
gsutil cp backup_$(date +%Y%m%d_%H%M%S).sql gs://your-backup-bucket/

Monitor Resources

# Check disk usage
df -h

# Check memory usage
free -h

# Check Docker stats
docker stats

🐛 Troubleshooting

Services Won’t Start

# Check logs for errors
docker compose logs

# Check disk space
df -h

# Check memory
free -h

# Restart Docker daemon
sudo systemctl restart docker
docker compose up -d

Cannot Connect to Database

# Check if PostgreSQL is running
docker compose ps postgres

# Check PostgreSQL logs
docker compose logs postgres

# Verify credentials in .env file
cat .env | grep POSTGRES

Port Already in Use

# Check what's using the port
sudo netstat -tulpn | grep :7130

# Kill the process or change port in docker-compose.yml

Out of Memory

Consider upgrading to a larger instance type:

- Current: e2-small (2 vCPU, 2 GB RAM)
- Upgrade to: e2-standard-2 (2 vCPU, 8 GB RAM)

SSL Certificate Issues

# Renew certificates
sudo certbot renew

# Test renewal
sudo certbot renew --dry-run

📊 Performance Optimization

For Production Workloads

Upgrade Instance Type: Use e2-standard-2 or e2-standard-4
Use Cloud SQL: Migrate from containerized PostgreSQL to Google Cloud SQL for better reliability
Enable Cloud Monitoring: Monitor metrics and set up alerts
Configure Backups: Set up automated daily backups
Use Cloud Storage: Configure Google Cloud Storage for file uploads instead of local storage

Database Optimization

# Increase PostgreSQL shared_buffers (edit postgresql.conf in deploy/docker-init/db/)
# Recommended: 25% of available RAM
shared_buffers = 1GB
effective_cache_size = 3GB

🔒 Security Best Practices

Change Default Passwords: Update admin and database passwords
Enable Firewall: Use Google Cloud Firewall rules effectively
Regular Updates: Keep system and Docker images updated
SSL/TLS: Always use HTTPS in production
Backup Regularly: Automate database backups
Monitor Logs: Set up log monitoring and alerts
Limit SSH Access: Restrict SSH to specific IP addresses
Use Service Accounts: Instead of API keys where possible

🆘 Support & Resources

Documentation: https://docs.insforge.dev
GitHub Issues: https://github.com/insforge/insforge/issues
Discord Community: https://discord.com/invite/MPxwj5xVvW

📝 Cost Estimation

Monthly Google Cloud Costs (approximate):

Component	Type	Monthly Cost
Compute Engine	e2-medium (2 vCPU, 4 GB RAM)	~$29
Persistent Disk (30 GB)	Standard	~$3
Network Egress	First 1GB free	Variable
Total		~$32/month

💡 Cost Optimization: Use sustained use discounts for 24/7 running instances to save up to 30%. Consider preemptible instances for development/testing environments.

Congratulations! 🎉 Your InsForge instance is now running on Google Cloud Compute Engine. You can start building applications by connecting AI agents to your backend platform. For other production deployment strategies, check out our deployment guides.

Getting Started

Products

Agent-Native Initiatives

Partnership

Self-Hosting

Resources

Documentation Index

​Deploy InsForge to Google Cloud Compute Engine

​📋 Prerequisites

​🚀 Deployment Steps

​1. Create and Configure Compute Engine Instance

​1.1 Create Google Cloud Project

​1.2 Enable Required APIs

​1.3 Create Compute Engine Instance

​1.4 Configure Firewall Rules

​2. Connect to Your Compute Engine Instance

​3. Install Dependencies

​3.1 Update System Packages

​3.2 Install Docker

​3.3 Add Your User to Docker Group

​3.4 Install Git

​4. Deploy InsForge

​4.1 Clone Repository

​4.2 Create Environment Configuration

​4.3 Start InsForge Services

​4.4 Verify Services

​5. Access Your InsForge Instance

​5.1 Test Backend API

​5.2 Access Dashboard

​6. Configure Domain (Optional but Recommended)

​6.1 Reserve a Static External IP

​6.2 Update DNS Records

​6.3 Install Nginx Reverse Proxy

​6.4 Install SSL Certificate (Recommended)

​🔧 Management & Maintenance

​View Logs

​Stop Services

​Restart Services

​Update InsForge

​Backup Database

​Monitor Resources

​🐛 Troubleshooting

​Services Won’t Start

​Cannot Connect to Database

​Port Already in Use

​Out of Memory

​SSL Certificate Issues

​📊 Performance Optimization

​For Production Workloads

​Database Optimization

​🔒 Security Best Practices

​🆘 Support & Resources

​📝 Cost Estimation

Deploy InsForge to Google Cloud Compute Engine

📋 Prerequisites

🚀 Deployment Steps

1. Create and Configure Compute Engine Instance

1.1 Create Google Cloud Project

1.2 Enable Required APIs

1.3 Create Compute Engine Instance

1.4 Configure Firewall Rules

2. Connect to Your Compute Engine Instance

3. Install Dependencies

3.1 Update System Packages

3.2 Install Docker

3.3 Add Your User to Docker Group

3.4 Install Git

4. Deploy InsForge

4.1 Clone Repository

4.2 Create Environment Configuration

4.3 Start InsForge Services

4.4 Verify Services

5. Access Your InsForge Instance

5.1 Test Backend API

5.2 Access Dashboard

6. Configure Domain (Optional but Recommended)

6.1 Reserve a Static External IP

6.2 Update DNS Records

6.3 Install Nginx Reverse Proxy

6.4 Install SSL Certificate (Recommended)

🔧 Management & Maintenance

View Logs

Stop Services

Restart Services

Update InsForge

Backup Database

Monitor Resources

🐛 Troubleshooting

Services Won’t Start

Cannot Connect to Database

Port Already in Use

Out of Memory

SSL Certificate Issues

📊 Performance Optimization

For Production Workloads

Database Optimization

🔒 Security Best Practices

🆘 Support & Resources

📝 Cost Estimation