Docker Compose Deployment

This page explains how to deploy Hagicode with Docker Compose. It suits servers, NAS, team sharing, or scenarios that need environment isolation; for personal local use, consider the Microsoft Store or Desktop first.

Why Choose Docker Compose

• Environment isolation means fewer dependency conflicts
• The currently supported Hagicode service stack can start together
• Configuration, upgrades, and maintenance follow one consistent path
• The host only needs Docker, and does not need Node.js or Git installed separately

About Default Data Storage

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

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

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

Follow the official Docker documentation to install Docker Engine and the Docker Compose plugin for your distribution: Install Docker Engine. Package sources and package names differ between distributions, so do not copy commands from another distribution directly.

After installation, start the Docker service and enable it at boot:

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 Docker Compose Builder to generate docker-compose.yml. It is a standalone site, and its generation rules and updates are governed by that site.

The generator supports:

• Choosing an API provider (Zhipu AI, Anthropic Official, or Custom API) and configuring the API URL and Token
• Customizing ports, container names, persistence directories, and working directories
• Choosing a built-in database or an external database
• Automatically handling Windows / Linux platform differences and common file-permission issues
• Using the supported Docker Hub image

Steps:

1. Open Docker Compose Builder.
2. Fill in the configuration according to your needs: choose an API provider, and configure ports, database, working directory, and other options.
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 hold sensitive information, so you do not write the Token directly into the compose file.

Image Source

The generator uses Docker Hub as the supported image source:

• Image Address: newbe36524/hagicode:{tag}
• Applicable Scenarios: Suitable for users with Docker Hub mirror acceleration
• Notes: Mirror acceleration may need to be configured in some regions

Get API Token

Docker deployments access models through the API provider you configure in the generator, so you need to prepare a working API Token first:

Zhipu AI: 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

You can also choose a custom API in the generator.

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 configuration
• 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 configuration in “running” status.

View 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

Access Application

After successful service startup, access through your browser:

http://localhost:45000

If you changed the port in the generator, use the host port you set. The first time you open it, you enter the initialization wizard; continue with Wizard Setup.

Configuration Instructions

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

1. Regenerate a new configuration using Docker Compose Builder
2. Manually edit the docker-compose.yml and .env files
3. Recreate the containers to make the configuration take effect:

docker compose up -d

docker compose restart only restarts the existing containers and does not apply changes made to docker-compose.yml or .env. After changing the configuration, use docker compose up -d.

Data Persistence

The currently 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 directly.

Routine Maintenance

Stop and Start

# Stop services (keeps containers and data)
docker compose stop

# Start again
docker compose start

# Stop and remove containers (data volumes are still kept)
docker compose down

Do not casually add -v to docker compose down; it also deletes the data volumes declared in the compose file.

Upgrade Version

1. Back up the data directory before upgrading (see below).
2. Change the image tag newbe36524/hagicode:{tag} in docker-compose.yml to the target version, or regenerate the configuration with the generator.
3. Pull the new image and recreate the containers:

docker compose pull
docker compose up -d

Back Up Data

First run docker compose stop so the service stops writing, then back up the directories or data volumes that the volume and data-directory mappings in docker-compose.yml point to, and finally run docker compose start to resume the service.

Next Steps

Now you have successfully deployed Hagicode. Next:

1. Read Wizard Setup to create your default Hagicoder and your first project.
2. In Create a Conversation Session, start in read-only mode to understand the project, then continue to Create Proposal Session as needed.

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