Quick Start

This page guides you to run iForge in a local development environment. For production deployment, please refer to Docker Deployment.

Environment Requirements

• Go 1.26+
• Node.js 18+
• Git (available in system PATH)
• Docker 20.10+ (optional, for CI/CD Job execution)

Start Backend

cd server
go run ./cmd/server

The backend will start at http://localhost:8081, including:

• HTTP API + Git HTTP protocol (port 8081)
• SSH Git protocol (port 2022)

Database

SQLite database (server/data/iforge.db) is automatically created on first startup, no manual migration required.

Start Frontend

cd web
npm install
npm run dev

The frontend will start at http://localhost:3001.

Initial Configuration

1. Open browser and visit http://localhost:3001
2. Click "Register" to create the first administrator account
3. Create your first repository
4. Start using Git to push code

# Clone repository (HTTP)
git clone http://localhost:8081/your-username/repository-name.git

# Or SSH
git clone ssh://git@localhost:2022/your-username/repository-name.git

Experience Task-Driven Development

iForge's core feature is deep integration of tasks and code. Here's a quick experience flow:

1. Create Project and Task

1. Enter the "Projects" page, create a new project
2. Create a task (Task) in the project board, for example: TASK-1: Fix login timeout issue
3. Set task priority, assignee

2. Create Development Branch from Task

Click "Create Branch" on the task card, the system automatically generates a branch in task-1-fix-login-timeout format:

# Fetch new branch
git fetch origin
git checkout task-1-fix-login-timeout

3. Develop and Commit (Reference Task Number)

# Reference task number when committing, automatically linked to task timeline
git commit -m "Optimize database connection pool configuration #TASK-1"
git push origin task-1-fix-login-timeout

4. Create Merge Request

After pushing the branch, create a merge request (MR) on the repository page, the system will automatically link the task. After merging, the task status is automatically updated to "Completed".

This is iForge's core philosophy: Requirements → Branches → Commits → MR → Merge → Task Completed, full-chain traceable.

Environment Variables

Development environment usually uses default values. For complete configuration, see Configuration.

Variable	Description	Default
IFORGE_HOME	Data directory	./data
IFORGE_HTTP_PORT	HTTP port	8081
IFORGE_SSH_PORT	SSH port	2022
IFORGE_CORS_ORIGINS	CORS allowed origins	localhost
IFORGE_CI_ENABLED	Whether to enable CI/CD	true
IFORGE_CI_ALLOW_SHELL_EXECUTOR	Whether to allow Shell Executor (must be false in production)	false

Security Notice

In production environment, you must keep IFORGE_CI_ALLOW_SHELL_EXECUTOR=false (default value) to prevent direct execution of user code on the host. See CI/CD Pipeline - Security Mechanism for details.

---

Next: Installation or Configuration.