Docker Compose Deployment

This guide covers deploying Hagicode with Docker Compose. For most users, this is the default deployment path across development, testing, and production environments.

Video Tutorial

If you want to see the full flow first, start with the video tutorial:

Watch the video tutorial on Bilibili

Video Content Includes:

Complete demonstration of Docker Compose deployment process
Configuration file generation and modification instructions
Service startup and verification steps
Common issues and solutions

Video duration: approximately 15 minutes

Docker Compose Builder

Docker Compose Builder is now available as a standalone tool at https://builder.hagicode.com/. Use that site as the main source for generating the same class of configuration files.

Use Configuration Generator

You can use Docker Compose Builder (standalone site) to generate docker-compose.yml directly.

The generator supports:

custom ports, container names, and other basic settings
built-in or external database selection
automatic Windows / Linux platform differences
common file-permission handling
image source selection based on your network environment

Open the generator →

Recommended Method

Docker Compose is the default deployment path in most cases because:

environment isolation reduces dependency conflicts
the supported Hagicode service stack can start together
configuration, upgrades, and maintenance are easier to keep consistent
it works well for local trials, testing, and team deployment

About Default Data Storage

The currently supported Docker Compose templates persist data through the default local SQLite path. In most cases, you do not need to provision a separate database service on the host machine.

Prerequisites

Before starting, ensure your system has Docker and Docker Compose installed.

Install Docker

Windows

Download and install Docker Desktop for Windows

After installation, ensure Docker Desktop is running.

macOS

Download and install Docker Desktop for Mac

After installation, ensure Docker Desktop is running.

Linux

Install Docker using your package manager:

sudo apt-get update
sudo apt-get install docker.io docker-compose-plugin

After installation, start Docker service:

sudo systemctl start docker
sudo systemctl enable docker

Verify Installation

After installation, run the following commands to verify Docker and Docker Compose are installed correctly:

docker --version
docker compose version

Quick Start

1. Generate Docker Compose Configuration File

Use Configuration Generator

Recommend using Docker Compose Builder (standalone site) to generate your configuration file.

The generator supports:

Multiple API provider options (Zhipu AI, Anthropic Official, Custom API)
Automatic configuration of API URL and Token
Custom ports, container names, and other basic configuration
Configure persistent data and working-directory paths
Automatically configure Windows/Linux platform differences
Intelligently handle file permission issues
Docker Hub Image: Generates the supported Docker Hub image reference

🚀 Use the generator immediately →

Open Docker Compose Builder (standalone site)
Fill in the configuration according to your needs:
- Select API provider (Zhipu AI, Anthropic Official, or Custom API)
- Configure ports, database, working directory, and other options
- Use Docker Hub Image: The generator configures the supported Docker Hub image
Click the generate button to get the docker-compose.yml configuration
Save the generated configuration as a docker-compose.yml file
If needed, create a .env file to configure sensitive information

Image Source

The generator uses Docker Hub as the supported image source:

Docker Hub

Image Address: newbe36524/hagicode:{tag}
Applicable Scenarios: Suitable for users with Docker Hub mirror acceleration
Advantages: Official image source, timely updates, stable access
Notes: Mirror acceleration may need to be configured in some regions

Get API Token

You need to configure Claude API Token to use Hagicode:

Zhipu AI (Recommended): Get API Token →

Stable domestic access, faster response
High cost-performance, suitable for daily use

Anthropic Official: Get API Token →

Direct use of Anthropic’s services

2. Start Services

Execute the following command in the directory where your docker-compose.yml is located:

docker compose up -d

This command will:

Download and start the Hagicode containers defined by the generated template
Create and configure the network
Initialize the default data directory and runtime dependencies

3. Verify Service Status

Check if containers are running:

docker compose ps

You should see the services defined in your generated template in “running” status.

View Service Logs

To view all service logs:

# View all service logs
docker compose logs

# View Hagicode service logs
docker compose logs hagicode

# Real-time log following
docker compose logs -f hagicode

Configuration Instructions

If you need to modify the configuration (such as changing ports, switching API provider, etc.), you can:

Regenerate new configuration using Docker Compose Builder (standalone site)
Manually edit docker-compose.yml and .env files
Restart services to make configuration take effect:

docker compose restart

Access Application

Web Interface

After successful service startup, access through your browser:

http://localhost:45000

Data Persistence

The supported Docker Compose path uses SQLite data files with persistent volumes by default. If you need to inspect mount points or plan backups, review the volume and data-directory mappings in the generated docker-compose.yml.

Next Steps

Now you have successfully deployed Hagicode. Next, connect a real project in the web interface, then continue with Wizard Setup or Create Proposal Session.

If you prefer the desktop application deployment method, please refer to Desktop Installation Guide.