chore: import upstream snapshot with attribution

docs/deployment/README.md

@@ -0,0 +1,103 @@
+# InsForge Deployment Guides
+
+This directory contains deployment guides for self-hosting InsForge on various platforms.
+
+## 📚 Available Guides
+
+### General (Any VPS)
+
+- **[Deployment & Security Guide](./deployment-security-guide.md)** - Comprehensive guide for any Linux VPS
+  - Full deployment walkthrough with Docker Compose
+  - Reverse proxy setup (Nginx & Caddy)
+  - Firewall, SSH hardening, and security best practices
+  - Update, rollback, and automated backup procedures
+
+### Cloud Platforms
+
+> Note: the cloud-provider walkthroughs (AWS, Azure, GCP) are community-maintained and can lag the current release.
+
+- **[AWS EC2](./deploy-to-aws-ec2.md)** - Deploy InsForge on Amazon EC2 with Docker Compose
+  - Instance setup and configuration
+  - Docker Compose deployment
+  - Domain and SSL configuration
+  - Production best practices
+
+- **[Google Cloud Compute Engine](./deploy-to-google-cloud-compute-engine.md)** - Deploy InsForge on Google Cloud Compute Engine with Docker Compose
+  - VM instance setup and configuration
+  - Docker Compose deployment
+  - Domain and SSL configuration
+  - Production best practices
+
+- **[Azure Virtual Machines](./deploy-to-azure-virtual-machines.md)** - Deploy InsForge on an Azure VM with Docker Compose
+  - VM instance setup and configuration
+  - Docker Compose deployment
+  - Domain and SSL configuration
+  - Production best practices
+
+- **[Containarium](./deploy-to-containarium.md)** - Deploy InsForge on a self-hosted Containarium host (LXC + MCP-native control plane)
+  - One-command box provisioning with Docker pre-installed
+  - Built-in TLS-on-a-hostname via Caddy + ACME
+  - Compose-autostart survives host reboots
+  - Multi-tenant: many isolated InsForge projects per host
+  - Optional agent-driven deploy via MCP
+
+### Coming Soon
+
+- **Digital Ocean** - Droplet deployment guide
+- **Hetzner** - VPS deployment guide
+- **Kubernetes** - Production-grade Kubernetes deployment
+- **Railway** - One-click Railway deployment
+- **Fly.io** - Global edge deployment
+
+## 🎯 Choosing a Platform
+
+### For Beginners
+- **AWS EC2** - Well-documented, widely used
+- **Railway** (Coming Soon) - One-click deployment
+
+### For Production
+- **AWS EC2** - Reliable, scalable, extensive features
+- **Kubernetes** (Coming Soon) - High availability, auto-scaling
+
+### For Cost-Conscious
+- **Hetzner** (Coming Soon) - Best price-to-performance ratio
+- **Digital Ocean** (Coming Soon) - Simple pricing, good performance
+
+### For Global Distribution
+- **AWS with CloudFront** - Global CDN integration
+- **Fly.io** (Coming Soon) - Edge deployment in multiple regions
+
+## 📋 General Requirements
+
+All deployment methods require:
+
+- Docker & Docker Compose support (for container-based deployments)
+- Minimum 2 GB RAM (4 GB recommended)
+- 20 GB storage (30 GB recommended)
+- PostgreSQL 15+ compatible
+- Internet connectivity for external services
+
+## 🔧 Architecture Overview
+
+InsForge consists of 4 main services:
+
+1. **PostgreSQL** - Database (port 5432)
+2. **PostgREST** - Auto-generated REST API (port 5430)
+3. **InsForge Backend** - Node.js API server, also serves the dashboard (port 7130)
+4. **Deno Runtime** - Serverless functions (port 7133)
+
+## 🤝 Contributing
+
+Have experience deploying InsForge on a platform not listed here? We'd love your contribution!
+
+1. Fork the repository
+2. Create a deployment guide following the AWS EC2 template
+3. Submit a pull request
+
+See [CONTRIBUTING.md](../../CONTRIBUTING.md) for more details.
+
+## 🆘 Need Help?
+
+- **Documentation**: [https://docs.insforge.dev](https://docs.insforge.dev)
+- **Discord Community**: [https://discord.com/invite/MPxwj5xVvW](https://discord.com/invite/MPxwj5xVvW)
+- **GitHub Issues**: [https://github.com/insforge/insforge/issues](https://github.com/insforge/insforge/issues)

docs/deployment/deploy-to-aws-ec2.md

@@ -0,0 +1,502 @@
+---
+title: "Deploy InsForge to AWS EC2"
+description: "Step-by-step guide to deploy InsForge on an AWS EC2 instance using Docker Compose, including SSH setup, domain config, and TLS termination."
+---
+
+# Deploy InsForge to AWS EC2
+
+This guide will walk you through deploying InsForge on an AWS EC2 instance 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
+
+- AWS Account with EC2 access
+- Basic knowledge of SSH and command-line operations
+- Domain name (optional, for custom domain setup)
+
+## 🚀 Deployment Steps
+
+### 1. Create and Configure EC2 Instance
+
+#### 1.1 Launch EC2 Instance
+
+1. **Log into AWS Console** and navigate to EC2 Dashboard
+2. **Click "Launch Instance"**
+3. **Configure Instance:**
+   - **Name**: `insforge-server` (or your preferred name)
+   - **AMI**: Ubuntu Server 24.04 LTS (HVM), SSD Volume Type
+   - **Instance Type**: `t3.medium` or larger (minimum 2 vCPU, 4 GB RAM)
+     - For production: `t3.large` (2 vCPU, 8 GB RAM) recommended
+     - For testing: `t3.small` (2 vCPU, 2 GB RAM) minimum
+   - **Key Pair**: Create new or select existing key pair (download and save the `.pem` file)
+   - **Storage**: 30 GB gp3 (minimum 20 GB recommended)
+
+#### 1.2 Configure Security Group
+
+Create or configure security group with the following inbound rules:
+
+| Type        | Protocol | Port Range | Source    | Description          |
+|-------------|----------|------------|-----------|----------------------|
+| SSH         | TCP      | 22         | My IP     | SSH access           |
+| HTTP        | TCP      | 80         | 0.0.0.0/0 | HTTP access          |
+| HTTPS       | TCP      | 443        | 0.0.0.0/0 | HTTPS access         |
+| Custom TCP  | TCP      | 7130       | 0.0.0.0/0 | Dashboard + API      |
+| Custom TCP  | TCP      | 5432       | 0.0.0.0/0 | PostgreSQL (optional)|
+
+> ⚠️ **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.
+
+#### 1.3 Allocate Elastic IP (Recommended)
+
+1. Navigate to **Elastic IPs** in EC2 Dashboard
+2. Click **Allocate Elastic IP address**
+3. Associate the Elastic IP with your instance
+
+This ensures your instance keeps the same IP address even after restarts.
+
+### 2. Connect to Your EC2 Instance
+
+```bash
+# Set correct permissions for your key file
+chmod 400 your-key-pair.pem
+
+# Connect via SSH
+ssh -i your-key-pair.pem ubuntu@your-ec2-public-ip
+```
+
+### 3. Install Dependencies
+
+#### 3.1 Update System Packages
+
+```bash
+sudo apt update && sudo apt upgrade -y
+```
+
+#### 3.2 Install Docker
+
+```text
+Follow the instructions of the link below to install and verify docker on your new ubuntu ec2 instance:
+https://docs.docker.com/engine/install/ubuntu/
+```
+
+#### 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 EC2 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
+
+Copy the example template to create your `.env` file:
+
+```bash
+cp .env.example .env
+nano .env
+```
+
+The full template lives at `deploy/docker-compose/.env.example`. These are the variables you must set:
+
+```env
+# Required
+JWT_SECRET=your-secret-key-here-must-be-32-char-or-above
+ROOT_ADMIN_USERNAME=admin
+ROOT_ADMIN_PASSWORD=change-this-password
+POSTGRES_PASSWORD=change-this-password
+
+# Optional: falls back to JWT_SECRET if left blank
+ENCRYPTION_KEY=
+
+# Optional: enables AI features
+OPENROUTER_API_KEY=
+
+# Optional: enables site deployments
+VERCEL_TOKEN=
+VERCEL_TEAM_ID=
+VERCEL_PROJECT_ID=
+
+# Optional: OAuth providers
+GOOGLE_CLIENT_ID=
+GOOGLE_CLIENT_SECRET=
+GITHUB_CLIENT_ID=
+GITHUB_CLIENT_SECRET=
+```
+
+The `.env.example` template carries the remaining variables and their defaults, so editing the copied file is enough.
+
+**Generate Secure Secrets:**
+
+```bash
+# Generate JWT_SECRET (32+ characters)
+openssl rand -base64 32
+
+# Generate ENCRYPTION_KEY (must be exactly 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-ec2-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-ec2-ip:7130
+```
+
+Log in with the `ROOT_ADMIN_USERNAME` and `ROOT_ADMIN_PASSWORD` you set in `.env`.
+
+### 6. Configure Domain (Optional but Recommended)
+
+#### 6.1 Update DNS Records
+
+Add DNS A records pointing to your EC2 Elastic IP:
+```text
+api.yourdomain.com    → your-ec2-ip
+app.yourdomain.com    → your-ec2-ip
+```
+
+#### 6.2 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 (served by the backend on the same port as the API)
+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.3 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
+
+InsForge ships prebuilt images, so an update is a pull and restart. Run this from `~/insforge/deploy/docker-compose`:
+
+```bash
+cd ~/insforge/deploy/docker-compose
+git pull origin main
+docker compose pull && docker compose up -d
+```
+
+### Backup Database
+
+Run these from `~/insforge/deploy/docker-compose`:
+
+```bash
+# Create backup
+docker compose exec postgres pg_dump -U postgres insforge > backup_$(date +%Y%m%d_%H%M%S).sql
+
+# Restore from backup
+cat backup_file.sql | docker compose exec -T postgres psql -U postgres -d insforge
+```
+
+### 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: t3.medium (4 GB RAM)
+- Upgrade to: t3.large (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 `t3.large` or `t3.xlarge`
+2. **Enable Auto-scaling**: Set up Application Load Balancer with auto-scaling groups
+3. **Use RDS**: Migrate from containerized PostgreSQL to AWS RDS for better reliability
+4. **Enable CloudWatch**: Monitor metrics and set up alarms
+5. **Configure Backups**: Set up automated daily backups
+6. **Use S3 for Storage**: Configure S3 bucket 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 AWS Security Groups 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 IAM Roles**: Instead of AWS access 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 AWS Costs (approximate):**
+
+| Component | Type | Monthly Cost |
+|-----------|------|--------------|
+| EC2 Instance | t3.medium | ~$30 |
+| Storage (30 GB) | EBS gp3 | ~$3 |
+| Elastic IP | (if running 24/7) | $0 |
+| Data Transfer | First 100GB free | Variable |
+| **Total** | | **~$33/month** |
+
+> 💡 **Cost Optimization**: Use AWS Savings Plans or Reserved Instances for long-term deployments to save up to 70%.
+
+---
+
+**Congratulations! 🎉** Your InsForge instance is now running on AWS EC2. 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).

docs/deployment/deploy-to-azure-virtual-machines.md

@@ -0,0 +1,289 @@
+# 📖 Deploying InsForge to Azure Virtual Machines (Extended Guide)
+
+This guide provides comprehensive, step-by-step instructions for deploying, managing, and securing InsForge on an Azure Virtual Machine (VM) 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
+
+* An active **Azure account**.
+* An **SSH client** to connect to the virtual machine.
+* Basic familiarity with the **Linux command line**.
+
+---
+
+## Step 1: 🖥️ Create an Azure Virtual Machine
+
+1.  **Log in to the [Azure Portal](https://portal.azure.com/)** and navigate to **Virtual machines**.
+2.  Click **+ Create** > **Azure virtual machine**.
+3.  **Basics Tab:**
+    * **Resource Group:** Create a new one (e.g., `insforge-rg`).
+    * **Virtual machine name:** `insforge-vm`.
+    * **Image:** **Ubuntu Server 22.04 LTS** or newer.
+    * **Size:** `Standard_B2s` (2 vCPUs, 4 GiB memory) is a good start. For production, consider `Standard_B4ms` (4 vCPUs, 16 GiB memory).
+    * **Authentication type:** **SSH public key**.
+    * **SSH public key source:** **Generate new key pair**. Name it `insforge-key`.
+4.  **Networking Tab:**
+    * In the **Network security group** section, click **Create new**.
+    * Add the following **inbound port rules** to allow traffic:
+        * `22` (SSH)
+        * `80` (HTTP for Nginx)
+        * `443` (HTTPS for Nginx/SSL)
+        * `7130` (InsForge API and dashboard)
+5.  **Review and Create:**
+    * Click **Review + create**, then **Create**.
+    * When prompted, **Download private key and create resource**. Save the `.pem` file securely.
+    * Once deployed, find and copy your VM's **Public IP address**.
+
+---
+
+## Step 2: ⚙️ Connect and Set Up the Server
+
+1.  **Connect via SSH:**
+    Open your terminal, give your key the correct permissions, and connect to the VM.
+
+    ```bash
+    chmod 400 /path/to/your/insforge-key.pem
+    ssh -i /path/to/your/insforge-key.pem azureuser@<your-vm-public-ip>
+    ```
+
+2.  **Update System Packages:**
+    ```bash
+    sudo apt update && sudo apt upgrade -y
+    ```
+
+3.  **Install Docker:**
+    Follow the official, up-to-date instructions on the Docker website to install Docker Engine on Ubuntu:
+    **[https://docs.docker.com/engine/install/ubuntu/](https://docs.docker.com/engine/install/ubuntu/)**
+
+4.  **Add Your User to the Docker Group:**
+    This step allows you 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. This command should now run without `sudo`:
+    ```bash
+    docker ps
+    ```
+    > 💡 **Note:** If `docker ps` doesn't work, log out of your SSH session and log back in, then try again.
+    >
+    > ⚠️ **Security Note:** Adding a user to the `docker` group grants them root-equivalent privileges. This is acceptable for a single-user VM but be cautious on shared systems.
+
+5.  **Install Git:**
+    ```bash
+    sudo apt install git -y
+    ```
+
+---
+
+## Step 3: 🚀 Deploy InsForge
+
+1.  **Clone the Repository:**
+    Navigate to your home directory and clone the InsForge project.
+    ```bash
+    cd ~
+    git clone https://github.com/InsForge/InsForge.git
+    cd InsForge/deploy/docker-compose
+    ```
+
+2.  **Create Environment Configuration:**
+    Create your `.env` file from the example and open it for editing.
+    ```bash
+    cp .env.example .env
+    nano .env
+    ```
+    `.env.example` lists every supported variable with comments. For a basic deployment you only need to set a few. Set these values and update the API URLs to your VM's public IP:
+
+    ```ini
+    # Required
+    JWT_SECRET=your-secret-key-here-must-be-32-char-or-above
+    ROOT_ADMIN_USERNAME=admin
+    ROOT_ADMIN_PASSWORD=change-this-password
+    POSTGRES_PASSWORD=change-this-password
+
+    # API URLs (replace with your VM public IP or domain)
+    API_BASE_URL=http://<your-vm-public-ip>:7130
+    VITE_API_BASE_URL=http://<your-vm-public-ip>:7130
+
+    # Optional
+    # ENCRYPTION_KEY falls back to JWT_SECRET if left empty
+    ENCRYPTION_KEY=
+    # OPENROUTER_API_KEY=
+    # VERCEL_TOKEN=
+    # GOOGLE_CLIENT_ID=
+    ```
+    The rest of `.env.example` covers optional features (OpenRouter, Vercel deployments, OAuth providers). Leave those blank unless you need them.
+    > **Generate a Secure JWT Secret:** Run this on your VM and paste the result into `JWT_SECRET`:
+    > ```bash
+    > openssl rand -base64 32
+    > ```
+
+3.  **Start InsForge Services:**
+    Pull the Docker images and start all services in the background.
+    ```bash
+    docker compose up -d
+    ```
+
+4.  **Verify Services:**
+    Check that all four containers are running.
+    ```bash
+    docker compose ps
+    ```
+    You should see the `postgres`, `postgrest`, `insforge`, and `deno` services running.
+
+---
+
+## Step 4: 🔑 Access Your InsForge Instance
+
+1.  **Test Backend API:**
+    Use `curl` to check the health endpoint.
+    ```bash
+    curl http://<your-vm-public-ip>:7130/api/health
+    ```
+    You should see a response like: `{"status":"ok", ...}`
+
+2.  **Access Dashboard:**
+    Open your browser and navigate to: `http://<your-vm-public-ip>:7130`
+    Log in with the `ROOT_ADMIN_USERNAME` and `ROOT_ADMIN_PASSWORD` you set in your `.env` file.
+
+---
+
+## Step 5: 🌐 Configure Domain (Optional but Recommended)
+
+1.  **Update DNS Records:**
+    In your domain provider's DNS settings, add two **A records** pointing to your VM's Public IP address:
+    * `api.yourdomain.com` → `<your-vm-public-ip>`
+    * `app.yourdomain.com` → `<your-vm-public-ip>`
+
+2.  **Install and Configure Nginx as a Reverse Proxy:**
+    ```bash
+    sudo apt install nginx -y
+    sudo nano /etc/nginx/sites-available/insforge
+    ```
+    Paste the following configuration:
+    ```nginx
+    # Backend API
+    server {
+        listen 80;
+        server_name api.yourdomain.com;
+        location / {
+            proxy_pass http://localhost:7130;
+            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;
+        }
+    }
+    # Frontend Dashboard (served by the same port as the API)
+    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;
+        }
+    }
+    ```
+    Enable the configuration and reload Nginx:
+    ```bash
+    sudo ln -s /etc/nginx/sites-available/insforge /etc/nginx/sites-enabled/
+    sudo nginx -t
+    sudo systemctl reload nginx
+    ```
+
+3.  **Install SSL Certificate with Certbot:**
+    ```bash
+    # Install Certbot for Nginx
+    sudo apt install certbot python3-certbot-nginx -y
+    # Obtain SSL certificates and configure Nginx automatically
+    sudo certbot --nginx -d api.yourdomain.com -d app.yourdomain.com
+    ```
+    Follow the prompts. Certbot will handle the rest.
+
+4.  **Update `.env` with HTTPS URLs:**
+    Edit your `.env` file and update the URLs.
+    ```bash
+    cd ~/InsForge
+    nano .env
+    ```
+    Change the URLs to `https`:
+    ```ini
+    API_BASE_URL=https://api.yourdomain.com
+    VITE_API_BASE_URL=https://api.yourdomain.com
+    ```
+    Restart the services for the changes to take effect:
+    ```bash
+    docker compose down && docker compose up -d
+    ```
+
+---
+
+## 🔧 Management & Maintenance
+
+* **View Logs:** `docker compose logs -f` (all services) or `docker compose logs -f insforge` (specific service).
+* **Stop Services:** `docker compose down`
+* **Restart Services:** `docker compose restart`
+* **Update InsForge:** Run these from `~/InsForge/deploy/docker-compose`. The images are prebuilt, so pull the latest tags instead of rebuilding.
+    ```bash
+    cd ~/InsForge/deploy/docker-compose
+    git -C ~/InsForge pull origin main
+    docker compose pull && docker compose up -d
+    ```
+* **Backup Database:** Run from `~/InsForge/deploy/docker-compose`.
+    ```bash
+    docker compose exec postgres pg_dump -U postgres insforge > backup_$(date +%Y%m%d_%H%M%S).sql
+    ```
+
+## 🐛 Troubleshooting
+
+* **Services Won't Start:** Check `docker compose logs` for errors. Ensure you have enough disk space (`df -h`) and memory (`free -h`).
+* **Port Already in Use:** Check which process is using the port with `sudo netstat -tulpn | grep :7130`.
+* **Out of Memory:** Consider upgrading your Azure VM to a size with more RAM.
+
+## 📊 Cost Estimation
+
+> **Disclaimer:** Prices are estimates based on Pay-As-You-Go rates in a common region (e.g., East US) and can vary. Always check the official [Azure Pricing Calculator](https://azure.microsoft.com/en-us/pricing/calculator/) for the most accurate information. On Azure, you pay for the VM's resources (CPU, RAM, Storage), which are shared by all the Docker services you run on it.
+
+### Free Tier (for Testing)
+* **Cost:** **~$0/month** for the first 12 months.
+* **Resources:** Azure provides a free tier that includes 750 hours/month of a `B1s` burstable VM.
+* **Limitations:** This VM has very limited resources (1 vCPU, 1 GiB RAM) and may run slowly. It's suitable only for basic testing and familiarization, not for active development or production.
+
+### Starter Setup (for Development & Small Projects)
+* **Cost:** **~$30 - $40/month**
+* **Resources:** This estimate is for a `Standard_B2s` VM (2 vCPU, 4 GiB RAM) running all the InsForge Docker containers.
+* **Breakdown:** The cost primarily consists of the VM compute hours. It also includes the OS disk storage and a static public IP address. This single VM runs your database, backend, Deno, and all other services.
+
+### Production Setup (for Scalability & Reliability)
+For production, you can choose between an all-in-one, larger VM or a more robust setup using managed services.
+
+* **Option A: All-in-One Larger VM**
+    * **Cost:** **~$150 - $170/month**
+    * **Resources:** A more powerful `Standard_B4ms` VM (4 vCPU, 16 GiB RAM) to handle higher traffic and all services.
+    * **Pros:** Simple to manage, consolidated cost.
+    * **Cons:** Database and application share resources, which can create performance bottlenecks. Scaling requires upgrading the entire VM.
+
+* **Option B: Managed Services (Recommended for Production)**
+    * **Cost:** **~$120+/month** (highly variable)
+    * **Resources:**
+        * **Application VM:** A `Standard_B2s` VM for the app services (InsForge, PostgREST, Deno). `(~$30/month)`
+        * **Managed Database:** Use **Azure Database for PostgreSQL** for reliability, automated backups, and scaling. `(~$40+/month for a starter tier)`
+    * **Pros:** Highly reliable and scalable. Database performance is isolated and guaranteed. Managed backups and security.
+    * **Cons:** More complex setup, costs are distributed across multiple services.
+
+## 🔒 Security Best Practices
+
+* **Change Default Passwords:** Always update admin and database passwords.
+* **Enable Firewall:** Use Azure **Network Security Groups (NSGs)** to restrict access to necessary ports and IP addresses.
+* **Regular Updates:** Periodically run `sudo apt update && sudo apt upgrade -y` and update InsForge.
+* **Backup Regularly:** Automate database and configuration backups.

docs/deployment/deploy-to-containarium.md

@@ -0,0 +1,290 @@
+---
+title: "Deploy InsForge to Containarium"
+description: "Run InsForge on a Containarium LXC host with per-tenant containers, ZFS snapshots, and MCP-driven provisioning for agent-native deployments."
+---
+
+# Deploy InsForge to Containarium
+
+This guide walks through deploying InsForge on a [Containarium](https://github.com/footprintai/containarium) host. Containarium is an open-source, self-hostable platform that gives each tenant a persistent Linux container (LXC) with first-class SSH, MCP, and TLS-on-a-hostname primitives — a natural fit for agent-driven InsForge deployments.
+
+<Note>
+  This guide 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>
+
+## When to choose Containarium
+
+Containarium fits InsForge deployments where you want:
+
+- **Self-hosted, multi-tenant infrastructure**: many isolated InsForge projects on one host, each in its own LXC, with one TLS hostname per project — no shared `docker compose -p` bookkeeping.
+- **Persistence and resilience**: ZFS-backed storage, daily snapshots with 30-day retention, automatic survival across host reboots and spot-VM termination.
+- **An agent-native control plane**: Containarium exposes its admin surface as an MCP server (`mcp-server`) and ships a second MCP that runs inside each container (`agent-box`), so the same agent that builds your app can also provision its backend end-to-end.
+
+## Prerequisites
+
+- A running Containarium host. If you don't have one, the [Containarium quickstart](https://github.com/footprintai/containarium#quick-start) takes ~5 minutes on a fresh Ubuntu 24.04 VM.
+- `containarium` CLI on your local machine, configured to reach the daemon (`--server <host>:8080`), or run the CLI directly on the host.
+- An admin token (`containarium token generate --username admin --roles admin --secret-file /etc/containarium/jwt.secret`).
+- A domain you control, with a DNS A/CNAME record pointing the chosen subdomain at your Containarium sentinel's public IP.
+
+Minimum sizing per InsForge box: **2 vCPU, 4 GB RAM, 30 GB disk**.
+
+## Deployment
+
+### 1. Provision a box with Docker pre-installed
+
+```bash
+containarium create insforge \
+  --stack docker \
+  --memory 4GB \
+  --cpu 2 \
+  --disk 30GB \
+  --ssh-key ~/.ssh/id_ed25519.pub
+```
+
+The `--stack docker` flag installs Docker CE and the compose plugin inside the container. Wire your SSH config so `ssh insforge` works:
+
+```bash
+containarium ssh-config sync
+# Then add one line to ~/.ssh/config:
+#   Include ~/.containarium/ssh_config
+ssh insforge
+```
+
+### 2. Clone InsForge inside the box
+
+```bash
+ssh insforge <<'EOF'
+  git clone https://github.com/InsForge/InsForge.git ~/insforge
+  cd ~/insforge/deploy/docker-compose
+  cp .env.example .env
+EOF
+```
+
+### 3. Configure environment
+
+Edit `~/insforge/deploy/docker-compose/.env` inside the box. At minimum set:
+
+```env
+JWT_SECRET=<32+ char random string — `openssl rand -base64 32`>
+ENCRYPTION_KEY=<24+ char random string — `openssl rand -base64 24`>
+POSTGRES_PASSWORD=<strong password>
+ROOT_ADMIN_USERNAME=admin
+ROOT_ADMIN_PASSWORD=<change this>
+
+API_BASE_URL=https://<your-subdomain>
+VITE_API_BASE_URL=https://<your-subdomain>
+```
+
+See [`deploy/docker-compose/.env.example`](https://github.com/insforge/insforge/blob/main/deploy/docker-compose/.env.example) for the full list (OpenRouter, OAuth providers, Stripe, Vercel).
+
+> **Secrets handling:** for production, prefer Containarium's tmpfs secrets (`--delivery=file`; see [Containarium's secrets ops doc](https://github.com/footprintai/Containarium/blob/main/docs/SECRETS-OPERATIONS.md)). These are delivered as 0440 files on tmpfs and never appear in `/proc/<pid>/environ`. Wire them into the compose stack via a compose override using `env_file:`.
+
+### 4. Start InsForge and enable autostart
+
+You can start it once by hand:
+
+```bash
+ssh insforge 'cd ~/insforge/deploy/docker-compose && docker compose up -d'
+```
+
+…or — recommended — wire it into Containarium's compose-autostart so the stack survives host reboots:
+
+```bash
+containarium compose enable insforge --dir /home/insforge/insforge/deploy/docker-compose
+```
+
+This installs a systemd-user unit inside the box that brings the stack up at every container boot and restarts services on failure with backoff. Verify with:
+
+```bash
+containarium compose status insforge
+```
+
+You should see `4/4 services up`: `postgres`, `postgrest`, `insforge`, `deno`. (The compose file ships healthchecks for `postgres`, `postgrest`, and `deno`; `insforge` reports `Up` once the others are healthy and it has started.)
+
+### 5. Expose on a public hostname
+
+InsForge serves the dashboard and API on port 7130 by default.
+
+```bash
+containarium expose-port insforge \
+  --container-port 7130 \
+  --domain <your-subdomain>
+```
+
+This wires Caddy on the Containarium sentinel to terminate TLS for `<your-subdomain>` and forward to the InsForge container. The certificate is provisioned automatically via ACME on the first request — no certbot, no nginx config.
+
+Verify:
+
+```bash
+curl https://<your-subdomain>/api/health
+```
+
+Expected:
+
+```json
+{
+  "status": "ok",
+  "version": "2.x.x",
+  "service": "Insforge OSS Backend",
+  "timestamp": "..."
+}
+```
+
+### 6. Connect your agent to InsForge MCP
+
+Open `https://<your-subdomain>` in a browser and follow the in-product flow to connect your MCP-compatible agent (Cursor, Claude Code, Windsurf, OpenCode, etc.) to the InsForge MCP server.
+
+Verify the connection by sending this prompt to your agent:
+
+```text
+I'm using InsForge as my backend platform, call InsForge MCP's
+fetch-docs tool to learn about InsForge instructions.
+```
+
+## Agent-driven deploy (optional)
+
+Because Containarium exposes its admin surface as an MCP server (`mcp-server`) and ships a second MCP inside every container (`agent-box`), an MCP-speaking agent can do the whole deployment end-to-end:
+
+```text
+agent: create me a container called 'insforge'
+  → mcp__containarium__create_container(
+      username="insforge", cpu="2", memory="4GB",
+      disk="30GB", stack="docker")
+
+agent: clone InsForge, fill in .env
+  → ssh insforge agent-box
+    → shell_exec("git clone https://github.com/InsForge/InsForge.git ~/insforge")
+    → write_file("~/insforge/deploy/docker-compose/.env", "<contents>")
+
+agent: enable autostart
+  → mcp__containarium__compose_enable(
+      username="insforge",
+      dir="/home/insforge/insforge/deploy/docker-compose")
+
+agent: expose on a public hostname
+  → mcp__containarium__expose_port(
+      username="insforge",
+      container_port=7130,
+      domain="<your-subdomain>")
+```
+
+See Containarium's [`docs/MCP-INTEGRATION.md`](https://github.com/footprintai/Containarium/blob/main/docs/MCP-INTEGRATION.md) for the platform MCP tool catalog.
+
+## Multi-tenant: many InsForge projects per host
+
+Each project gets its own LXC and its own hostname; the sentinel routes by SNI. No port collisions (each container has its own network namespace), no shared compose project names.
+
+```bash
+containarium create insforge-acme  --stack docker --memory 4GB --cpu 2 ...
+containarium create insforge-globex --stack docker --memory 4GB --cpu 2 ...
+
+containarium expose-port insforge-acme   --container-port 7130 \
+  --domain acme.<your-domain>
+containarium expose-port insforge-globex --container-port 7130 \
+  --domain globex.<your-domain>
+```
+
+Each project gets isolated postgres / storage / deno volumes.
+
+## Management
+
+### View logs
+
+```bash
+ssh insforge 'cd ~/insforge/deploy/docker-compose && docker compose logs -f'
+```
+
+Or per service: `docker compose logs -f insforge` / `postgres` / `deno`.
+
+### Update InsForge
+
+```bash
+ssh insforge <<'EOF'
+  cd ~/insforge/deploy/docker-compose
+  git -C ~/insforge pull origin main
+  docker compose pull
+  docker compose up -d
+EOF
+```
+
+If compose-autostart is enabled, no need to re-enable the unit — it tracks the directory, not a specific image tag.
+
+### Back up the database
+
+```bash
+ssh insforge 'cd ~/insforge/deploy/docker-compose && docker compose exec -T postgres \
+  pg_dump -U postgres insforge' > backup_$(date +%Y%m%d_%H%M%S).sql
+```
+
+Containarium also snapshots the entire container daily via ZFS (30-day retention by default), covering the postgres data volume as a point-in-time-restore backstop.
+
+### Stop / restart
+
+```bash
+containarium compose disable insforge   # stop the compose stack and disable autostart
+containarium sleep insforge             # stop the entire box
+containarium wake insforge              # start the box; compose comes up via autostart
+```
+
+## Troubleshooting
+
+### `containarium compose enable` fails
+
+Verify Docker is working inside the box:
+
+```bash
+ssh insforge 'docker ps'
+```
+
+If you skipped `--stack docker` at create time, either install it manually inside the box or recreate with the flag.
+
+### Public hostname doesn't resolve
+
+`containarium expose-port` configures Caddy on the sentinel; the DNS A/CNAME record for your subdomain must point at the sentinel's public IP. Check:
+
+```bash
+dig +short <your-subdomain>
+```
+
+### Hostname resolves but returns 502
+
+Check that InsForge is reachable from inside the box:
+
+```bash
+ssh insforge 'curl -s http://localhost:7130/api/health'
+```
+
+If the in-box check is fine, the bridge between sentinel and box is the next thing to investigate — see Containarium's [`docs/TUNNEL-REVERSE-PROXY.md`](https://github.com/footprintai/Containarium/blob/main/docs/TUNNEL-REVERSE-PROXY.md).
+
+### Out of memory after `docker compose up`
+
+InsForge's four services need ~3 GB resident at idle. If you sized the box at 2 GB, resize:
+
+```bash
+containarium resize insforge --memory 4GB
+containarium sleep insforge && containarium wake insforge
+```
+
+## Limitations
+
+- **AUTH_PORT (7131) and DENO_PORT (7133)** are not exposed externally by the steps above. If your app calls the standalone auth endpoint or direct Deno function URLs from outside the box, add additional `expose-port` calls with separate subdomains.
+- **`containarium compose enable` requires Containarium v0.18 or later** (the compose-autostart feature). On earlier versions, run `docker compose up -d` and add a `@reboot` cron entry by hand.
+- **GPU passthrough**: Containarium supports it, but InsForge's stock edge functions don't use GPU. Leave it off unless your custom Deno functions need it.
+
+## Security notes
+
+- The container's user is unprivileged on the host (LXC unprivileged mode); container root ≠ host root.
+- The sentinel front-door supports source-IP allowlists for admin endpoints — see Containarium's [security runbook](https://github.com/footprintai/Containarium/blob/main/docs/security/OPERATOR-SECURITY-RUNBOOK.md).
+- For production, opt into Containarium's KMS envelope encryption (Vault Transit or GCP KMS) for any InsForge secrets stored in Containarium's secret store.
+- Use `containarium token generate --scopes containers:read,containers:write ...` to mint least-privilege tokens for agents rather than handing out admin tokens.
+
+## Resources
+
+- **Containarium**: https://github.com/footprintai/containarium
+- **Containarium docs**: https://github.com/footprintai/Containarium/tree/main/docs
+- **InsForge docs**: https://docs.insforge.dev
+- **InsForge Discord**: https://discord.com/invite/MPxwj5xVvW
+
+---
+
+For other deployment strategies, see the [deployment guides](/deployment/deployment-security-guide).

docs/deployment/deploy-to-google-cloud-compute-engine.md

@@ -0,0 +1,555 @@
+---
+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).

docs/deployment/telemetry.mdx

@@ -0,0 +1,48 @@
+---
+title: "Anonymous self-host telemetry"
+description: "Learn what anonymous usage data InsForge self-hosted deployments send, what is never collected, and how to opt out using INSFORGE_TELEMETRY_DISABLED."
+---
+
+InsForge collects anonymous telemetry from self-hosted deployments to understand active installs, version adoption, deployment methods, and which optional services are configured. This helps maintainers prioritize fixes, security notices, and deployment work for the open-source project.
+
+Telemetry is optional. You can disable it at any time.
+InsForge does not send this telemetry from InsForge Cloud.
+Self-hosted events include a coarse runtime label, such as production, development, test, ci, or unknown, so maintainers can separate local and automated runs from production deployments.
+
+## What InsForge sends
+
+InsForge sends an `oss_instance_started` event when the backend starts and an `oss_heartbeat` event about once every 24 hours while the backend is running.
+Events are sent through InsForge's PostHog proxy at `https://b.insforge.dev/capture/` using PostHog's capture API format.
+
+Each event contains:
+
+- PostHog event name: `oss_instance_started` or `oss_heartbeat`
+- Anonymous installation ID stored locally in `LOGS_DIR/.insforge-installation-id`, used as the PostHog `distinct_id`
+- InsForge version
+- Event timestamp
+- Hosting mode, such as `self-hosted` or `cloud`
+- Coarse deployment method, such as Docker Compose, Railway, Zeabur, Sealos, Dokploy, Kubernetes, or unknown
+- Operating system, CPU architecture, Node.js version, runtime environment, and whether the process appears to be running in CI
+- Storage backend category: local filesystem, S3, or S3-compatible
+- Boolean flags for whether optional features are configured: site deployments, functions, compute, and OpenRouter
+
+## What InsForge never sends
+
+Telemetry does not include:
+
+- Environment variable values
+- API keys, JWT secrets, passwords, OAuth secrets, or payment secrets
+- Database contents, schemas, table names, or row counts
+- Logs, error stack traces, file contents, or file paths
+- Project names, domains, bucket names, email addresses, or user data
+
+## Disable telemetry
+
+Set `INSFORGE_TELEMETRY_DISABLED=1` in your environment and restart the backend.
+For Docker Compose deployments, add the same line to your `.env` file:
+
+```bash
+INSFORGE_TELEMETRY_DISABLED=1
+```
+
+Network failures are logged and ignored so telemetry never blocks startup or normal requests.