---
title: "Deploy InsForge to Google Cloud Compute Engine"
description: "Deploy InsForge on a Google Cloud Compute Engine VM with Docker Compose, covering firewall rules, SSH access, custom domains, and HTTPS setup."
---

# Deploy InsForge to Google Cloud Compute Engine

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

<Note>
  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](https://github.com/InsForge/InsForge).
</Note>

## 📋 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

1. **Log into Google Cloud Console** at [console.cloud.google.com](https://console.cloud.google.com)
2. **Click "Select a project"** in the top navigation bar
3. **Click "New Project"**
4. **Enter project name** (e.g., `insforge-deployment`)
5. **Click "Create"**
6. **Wait for project creation to complete**

#### 1.2 Enable Required APIs

1. In your project, navigate to **APIs & Services** → **Library**
2. 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

1. Navigate to **Compute Engine** → **VM instances**
2. Click **"Create Instance"**
3. 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

1. Navigate to **VPC network** → **Firewall**
2. 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

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

```bash
# 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

```bash
sudo apt update && sudo apt upgrade -y
```

#### 3.2 Install Docker

```bash
# 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`:

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

# Apply the group changes
newgrp docker
```

**Verify it works:**

```bash
# 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

```bash
sudo apt install git -y
```

### 4. Deploy InsForge

#### 4.1 Clone Repository

```bash
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:

```bash
nano .env
```

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

```bash
cp .env.example .env
nano .env
```

At a minimum, set these values:

```env
# 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)
ROOT_ADMIN_USERNAME=admin
ROOT_ADMIN_PASSWORD=change-this-password

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

Optional values you may want to set:

```env
# 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:**

```bash
# 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

```bash
# 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

```bash
# 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

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

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

#### 5.2 Access Dashboard

Open your browser and navigate to:
```text
http://your-external-ip:7130
```

### 6. Configure Domain (Optional but Recommended)

#### 6.1 Reserve a Static External IP

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

#### 6.2 Update DNS Records

Point your domain's DNS records to the reserved static IP:
```text
api.yourdomain.com    → your-static-external-ip
app.yourdomain.com    → your-static-external-ip
```

#### 6.3 Install Nginx Reverse Proxy

```bash
sudo apt install nginx -y
```

Create Nginx configuration:

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

Add the following configuration:

```nginx
# 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:

```bash
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)

```bash
# 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:

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

Change:
```env
API_BASE_URL=https://api.yourdomain.com
VITE_API_BASE_URL=https://api.yourdomain.com
```

Restart services:

```bash
docker compose down
docker compose up -d
```

## 🔧 Management & Maintenance

### View Logs

```bash
# 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

```bash
docker compose down
```

### Restart Services

```bash
docker compose restart
```

### Update InsForge

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

### Backup Database

```bash
# 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

```bash
# Check disk usage
df -h

# Check memory usage
free -h

# Check Docker stats
docker stats
```

## 🐛 Troubleshooting

### Services Won't Start

```bash
# 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

```bash
# 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

```bash
# 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:
```text
- Current: e2-small (2 vCPU, 2 GB RAM)
- Upgrade to: e2-standard-2 (2 vCPU, 8 GB RAM)
```

### SSL Certificate Issues

```bash
# Renew certificates
sudo certbot renew

# Test renewal
sudo certbot renew --dry-run
```

## 📊 Performance Optimization

### For Production Workloads

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

### Database Optimization

```conf
# 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

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

## 🆘 Support & Resources

- **Documentation**: [https://docs.insforge.dev](https://docs.insforge.dev)
- **GitHub Issues**: [https://github.com/insforge/insforge/issues](https://github.com/insforge/insforge/issues)
- **Discord Community**: [https://discord.com/invite/MPxwj5xVvW](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](/deployment/deployment-security-guide).