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:

Install Docker on Ubuntu/Debian

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
• Image Source Selection: Based on your network environment, select the appropriate image source

🚀 Use the generator immediately →

1. Open Docker Compose Builder (standalone site)
2. 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
   • Select Image Source: Choose the appropriate image source based on your network environment
3. Click the generate button to get the docker-compose.yml configuration
4. Save the generated configuration as a docker-compose.yml file
5. If needed, create a .env file to configure sensitive information

Image Source Selection

The generator supports three image source options:

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

Azure Container Registry (ACR)

• Image Address: hagicode.azurecr.io/hagicode:{tag}
• Applicable Scenarios: Suitable for users unable to access Docker Hub locally
• Advantages: Provides alternative image source, resolves network access issues
• Notes: Images stay synchronized with Docker Hub, but may have brief delays

Alibaba Cloud Container Registry (ACR)

• Image Address: registry.cn-hangzhou.aliyuncs.com/hagicode/hagicode:{tag}
• Applicable Scenarios: Suitable for domestic users, stable and fast network access
• Advantages: Alibaba Cloud domestic nodes, fast access speed, high stability
• Notes: Alibaba ACR images stay synchronized with Docker Hub, usually within 30 minutes

Image Source Selection Recommendations

• Domestic Users Recommend Alibaba Cloud ACR: If you are a domestic user, it’s recommended to prioritize using Alibaba Cloud ACR image source for fast and stable access
• Alternative Docker Hub: If your network environment can access Docker Hub, you can also choose Docker Hub as image source
• Alternative Azure ACR: Only choose Azure ACR image source if other image sources have access difficulties
• Image Synchronization: Alibaba Cloud ACR images stay synchronized with Docker Hub, usually within 30 minutes
• Version Consistency: Image tags are consistent across all three image sources, no need to worry about version issues

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:

1. Regenerate new configuration using Docker Compose Builder (standalone site)
2. Manually edit docker-compose.yml and .env files
3. 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.