Docker Compose Deployment

This guide introduces how to use Docker Compose for one-click deployment of the complete Hagicode system. This is the recommended deployment method, suitable for most users, especially for development, testing, and production environments.

Video Tutorial

To help you better understand the Docker Compose deployment process, we provide a detailed 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 an independent tool at: https://builder.hagicode.com/. It provides the same functionality and is regularly updated to improve user experience.

Use Configuration Generator

Recommend using Docker Compose Builder (standalone site)!

By filling out a simple form, you can quickly generate a docker-compose.yml configuration file that meets your needs. The generator supports:

• Custom ports, container names, and other basic configuration
• Select built-in database or external database
• 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 →

Recommended Method

Docker Compose deployment is the preferred installation method with the following advantages:

• Environment isolation, avoiding dependency conflicts
• One-click startup of all services (PostgreSQL + Hagicode)
• Easy to manage and maintain
• Suitable for quick experience and testing

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
• Select built-in database or external database
• 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 PostgreSQL container
• Download and start the Hagicode application container
• Create and configure the network
• Initialize the database connection

3. Verify Service Status

Check if containers are running:

docker compose ps

You should see both containers 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

Database Connection

If you need to connect directly to the PostgreSQL database, you can use the docker exec command to enter the container:

# Enter PostgreSQL container and connect to database
docker exec -it hagicode-postgres psql -U postgres -d hagicode

Container Connection Information:

• Host: localhost or 127.0.0.1 (inside container)
• Port: 5432 (PostgreSQL default port)
• Username: postgres
• Password: postgres
• Database: hagicode

Tip

PostgreSQL is not exposed to the host port, which is more secure and avoids port conflicts. If you need to access the database from the host, please use the docker exec command.

Next Steps

Now you have successfully deployed Hagicode, please continue Create Your First Project to start using.

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