> ## Documentation Index
> Fetch the complete documentation index at: https://docs.insforge.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Deploy InsForge to Google Cloud Compute Engine

> 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 theme={null}
# 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 theme={null}
sudo apt update && sudo apt upgrade -y
```

#### 3.2 Install Docker

```bash theme={null}
# 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 theme={null}
# Add your user to the docker group
sudo usermod -aG docker $USER

# Apply the group changes
newgrp docker
```

**Verify it works:**

```bash theme={null}
# 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 theme={null}
sudo apt install git -y
```

### 4. Deploy InsForge

#### 4.1 Clone Repository

```bash theme={null}
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 theme={null}
nano .env
```

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

```bash theme={null}
cp .env.example .env
nano .env
```

At a minimum, set these values:

```env theme={null}
# 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 theme={null}
# 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 theme={null}
# 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 theme={null}
# 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 theme={null}
# 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 theme={null}
curl http://your-external-ip:7130/api/health
```

Expected response:

```json theme={null}
{
  "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 theme={null}
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 theme={null}
api.yourdomain.com    → your-static-external-ip
app.yourdomain.com    → your-static-external-ip
```

#### 6.3 Install Nginx Reverse Proxy

```bash theme={null}
sudo apt install nginx -y
```

Create Nginx configuration:

```bash theme={null}
sudo nano /etc/nginx/sites-available/insforge
```

Add the following configuration:

```nginx theme={null}
# 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 theme={null}
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 theme={null}
# 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 theme={null}
cd ~/insforge/deploy/docker-compose
nano .env
```

Change:

```env theme={null}
API_BASE_URL=https://api.yourdomain.com
VITE_API_BASE_URL=https://api.yourdomain.com
```

Restart services:

```bash theme={null}
docker compose down
docker compose up -d
```

## 🔧 Management & Maintenance

### View Logs

```bash theme={null}
# 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 theme={null}
docker compose down
```

### Restart Services

```bash theme={null}
docker compose restart
```

### Update InsForge

```bash theme={null}
cd ~/insforge/deploy/docker-compose
git pull origin main
docker compose pull && docker compose up -d
```

### Backup Database

```bash theme={null}
# 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 theme={null}
# Check disk usage
df -h

# Check memory usage
free -h

# Check Docker stats
docker stats
```

## 🐛 Troubleshooting

### Services Won't Start

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

### SSL Certificate Issues

```bash theme={null}
# 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 theme={null}
# 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).