Docker Deployment

Docker Compose is the recommended production deployment method for iForge.

One-Click Start

# 1. Clone the repository
git clone https://gitee.com/iforge-go/iforge.git
cd iforge

# 2. Copy environment variable configuration (optional, use defaults if not copied)
cp .env.example .env

# 3. Build and start (first build takes about 5-10 minutes)
docker compose up -d

# 4. View logs
docker compose logs -f

After startup, visit http://localhost:3000 to register the first administrator account.

Service Architecture

┌─────────────────────────────────────────────────────────────┐
│                    Nginx Reverse Proxy Layer                 │
│              (Managed in separate repo iforge-nginx)         │
│                                                              │
│  iforge-go.com ──────► iforge-site (Documentation site)     │
│  www.iforge-go.com ──► iforge-site (Documentation site)     │
│  demo.iforge-go.com ─┬─► iforge-web (Frontend)              │
│                      └─► iforge-server (Backend)            │
└─────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────┼─────────────────────────────────┐
│                        iForge Platform                        │
│                                                                │
│  ┌─────────────┐     ┌─────────────┐     ┌─────────────────┐ │
│  │  web:3001   │────▶│ server:8081 │────▶│   Database      │ │
│  │  (Next.js)  │     │   (Go)      │     │  SQLite/MySQL/  │ │
│  └─────────────┘     └──────┬──────┘     │  PostgreSQL     │ │
│                             │             └─────────────────┘ │
│                      ┌──────┴──────┐                          │
│                      │ server:2022 │                          │
│                      │ (SSH Git)   │                          │
│                      └─────────────┘                          │
│                             ▲                                 │
│                             │ claim job / report status       │
│                      ┌──────┴──────┐     ┌─────────────────┐ │
│                      │  runner     │────▶│  job container  │ │
│                      │ (iforge-    │ DooD│ (alpine, etc.)  │ │
│                      │  runner)    │     └─────────────────┘ │
│                      └─────────────┘                          │
└───────────────────────────────────────────────────────────────┘

Port Mapping

Service	Container Port	Host Port	Purpose
server	8081	8080	HTTP API + Git HTTP
server	2022	22	SSH Git protocol
web	3001	3000	Frontend pages
mysql	3306	3306	MySQL database (profile: mysql)
postgres	5432	5432	PostgreSQL database (profile: postgres)
runner	—	—	No external port, executes jobs via Docker socket

Data Persistence

Data volumes are mounted in the ./data directory:

volumes:
  - ./data:/app/data

Includes:

iforge.db — SQLite database
logs/ — Runtime logs
repositories/ — Git repository bare storage

Backup

Simply package the ./data directory for a complete backup.

LAN Access

Docker deployment supports LAN access by default, no additional configuration required:

Frontend API address dynamically adapts to browser hostname
Backend CORS is set to * (reflects any Origin)

Access http://192.168.x.x:3000 from other machines on the LAN, API requests are automatically sent to http://192.168.x.x:8080.

Custom Domain

When deploying to your own domain, set in .env:

NEXT_PUBLIC_API_BASE=https://iforge.example.com/api/v1
IFORGE_CORS_ORIGINS=https://iforge.example.com

Rebuild after modification:

docker compose build --no-cache web server
docker compose up -d

Database Selection

iForge supports three databases, switched through Docker Compose profiles:

SQLite (Default, Suitable for Development)

docker compose up -d

MySQL (Production Environment)

# Set in .env
IFORGE_DB_DRIVER=mysql
MYSQL_ROOT_PASSWORD=<strong-password>
MYSQL_PASSWORD=<strong-password>

docker compose --profile mysql up -d

PostgreSQL (Production Environment)

# Set in .env
IFORGE_DB_DRIVER=postgres
POSTGRES_PASSWORD=<strong-password>

docker compose --profile postgres up -d

Reverse Proxy Configuration

For production environments, it's recommended to use Nginx as a reverse proxy. iForge provides an independent iforge-nginx repository for unified Nginx configuration management.

Domain Planning

Domain	Service	Description
`iforge-go.com`	iforge-site	Official documentation site
`www.iforge-go.com`	iforge-site	Official documentation site
`demo.iforge-go.com`	iforge-web + iforge-server	Demo platform

Nginx Configuration Example

upstream iforge_web {
    server iforge-web:3001;
}

upstream iforge_server {
    server iforge-server:8081;
}

server {
    listen 443 ssl http2;
    server_name demo.iforge-go.com;

    ssl_certificate /etc/nginx/ssl/iforge-go.com.pem;
    ssl_certificate_key /etc/nginx/ssl/iforge-go.com.key;

    # Frontend
    location / {
        proxy_pass http://iforge_web;
        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;
    }

    # API
    location /api/ {
        proxy_pass http://iforge_server;
        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;
        client_max_body_size 100M;
    }
}

For detailed instructions, please refer to the iforge-nginx repository.

Common Commands

docker compose up -d          # Start
docker compose down           # Stop
docker compose restart        # Restart
docker compose logs -f server # View backend logs
docker compose logs -f web    # View frontend logs
docker compose build --no-cache  # Rebuild (after code changes)

CI/CD Runner Deployment

iforge-runner is an independent project, deployed separately from the iforge backend. It uses DooD mode (Docker-out-of-Docker): the runner itself runs in a container, creating sibling containers to execute jobs by mounting the host's Docker socket.

┌─────────────────────────────────────────────────────────┐
│  Host                                                    │
│                                                         │
│  ┌──────────────┐    docker.sock    ┌────────────────┐ │
│  │ iforge-runner│──────────────────▶│  Docker Daemon │ │
│  │  (container) │                   │  (host)        │ │
│  └──────┬───────┘                   └───────┬────────┘ │
│         │ docker run                          │          │
│         └────────────────────────────────────▶│          │
│                                            ┌──▼────────┐ │
│                                            │ job       │ │
│                                            │ container │ │
│                                            │ (sibling) │ │
│                                            └───────────┘ │
└─────────────────────────────────────────────────────────┘

Prerequisites

The iforge backend (server) must be running on the same host (default port 8080). If the backend is on another machine, you need to adjust the IFORGE_RUNNER_SERVER environment variable.

First Deployment

The Runner needs to register and obtain a token before it can start. The first deployment is done in two steps:

Step 1: Register Runner (get token)

cd iforge-runner                    # Enter the runner's independent project directory
cp .env.example .env

# Set the absolute path of the host working directory (required for DooD path alignment)
# Replace with your actual path
echo 'IFORGE_RUNNER_HOST_WORKDIR=/home/admin/code/iforge-runner/data' >> .env

# Build the image and execute the one-time registration command
docker compose run --rm runner register \
  --server http://host.docker.internal:8081 \
  --name prod-runner \
  --admin <admin-username> \
  --password <admin-password>

# Example output:
#   Registration successful!
#     Runner Name: prod-runner
#     Token:       grt_xxxxxxxxxxxxxxxxxxxx

Step 2: Write token and start

# Write the token returned in the previous step to .env
echo 'IFORGE_RUNNER_TOKEN=grt_xxxxxxxxxxxxxxxxxxxx' >> .env

# Start runner
docker compose up -d

# Verify status
docker compose logs -f
# You should see: [runner] Started, server=http://host.docker.internal:8081, workDir=/work, hostWorkDir=... (DooD mode)

Subsequent Deployments

The token has been persisted in .env, so subsequent startups can be done with one click:

cd iforge-runner
docker compose up -d

Update Runner

cd iforge-runner
git pull
docker compose build --no-cache
docker compose up -d

Multi-Runner Expansion

Repeat the registration command to create multiple runners, each using a different name and token. You can define multiple runner service instances through docker-compose.override.yml for horizontal scaling.

Path Alignment

IFORGE_RUNNER_HOST_WORKDIR is a key configuration for DooD mode. The runner container's /work is mapped to the host's ./data through bind mount, but when the runner creates job containers through the docker CLI, the Docker daemon needs the host's absolute path to mount. This environment variable converts the container's internal path to the host's path, ensuring that the job container's /workspace is not empty.

Update Version

git pull
docker compose build --no-cache server web
docker compose up -d

Data Migration

iForge uses versioned SQL migrations, which are automatically executed during upgrades. Please ensure the ./data directory is backed up.

Security Configuration

CI/CD Security

During Docker deployment, CI/CD Job containers have the following security restrictions applied by default:

# docker-compose.yml server service environment variables
environment:
  - IFORGE_CI_ENABLED=true
  - IFORGE_CI_ALLOW_SHELL_EXECUTOR=false  # Must be false in production
  - IFORGE_CI_KEEP_WORKDIR=false          # Auto-cleanup working directory

Job container runtime restrictions:

--memory=2g: Memory limit 2GB
--memory-swap=2g: Prohibit swap usage
--cpus=2: CPU limit 2 cores
--pids-limit=256: Process limit
--network=none: Network access disabled by default

Security Warning

Never set IFORGE_CI_ALLOW_SHELL_EXECUTOR=true in production, as this will cause user code to execute directly on the host, posing serious security risks.

One-Click Start​

Service Architecture​

Port Mapping​

Data Persistence​

LAN Access​

Custom Domain​

Database Selection​

SQLite (Default, Suitable for Development)​

MySQL (Production Environment)​

PostgreSQL (Production Environment)​

Reverse Proxy Configuration​

Domain Planning​

Nginx Configuration Example​

Common Commands​

CI/CD Runner Deployment​

First Deployment​

Subsequent Deployments​

Update Runner​

Multi-Runner Expansion​

Update Version​

Security Configuration​

CI/CD Security​