Installation Guide

This guide covers detailed installation methods for deploying Halo in production environments. Choose the method that best fits your infrastructure and requirements.

For a quick test installation, see the Quick Start guide.

Installation Methods

Docker

Recommended for most users - simple, portable, and consistent across platforms

Docker Compose

Best for production - easier configuration and multi-container orchestration

1Panel

Recommended for production - includes reverse proxy, SSL, and backup automation

Manual Installation

Advanced users who need custom configurations

System Requirements

Before installing Halo, ensure your system meets these requirements:

Minimum Requirements

CPU: 1 core
RAM: 512MB (1GB recommended)
Storage: 10GB free space
Operating System: Linux, macOS, or Windows
Java: JRE 21 or higher (for manual installation)

Software Requirements

Docker 20.10+ (for Docker/Docker Compose installation)
Docker Compose 2.0+ (for Docker Compose installation)

Halo requires port 8090 by default. Ensure this port is available or configure a different port.

Docker Installation

The Docker installation method provides the simplest way to run Halo with all dependencies included.

Basic Docker Deployment

Pull the Halo image

docker pull halohub/halo:2.22

Create data directory

mkdir -p ~/.halo2

This directory will store all your Halo data including database files, uploads, and configuration.

Run Halo container

docker run -d \
  --name halo \
  -p 8090:8090 \
  -v ~/.halo2:/root/.halo2 \
  halohub/halo:2.22

Halo will use the embedded H2 database by default, which is suitable for small to medium sites.

Access Halo

Open your browser and navigate to http://localhost:8090 to complete the setup wizard.

Docker with Environment Variables

You can customize Halo’s behavior using environment variables:

docker run -d \
  --name halo \
  -p 8090:8090 \
  -v ~/.halo2:/root/.halo2 \
  -e JVM_OPTS="-Xmx512m -Xms512m" \
  -e TZ=America/New_York \
  halohub/halo:2.22

Common environment variables:

JVM_OPTS: JVM options for memory configuration
TZ: Timezone (defaults to Asia/Shanghai)
HALO_WORK_DIR: Working directory (defaults to /root/.halo2)

Docker Compose Installation

Docker Compose provides better configuration management and is recommended for production deployments.

Basic Docker Compose Setup

Create docker-compose.yml

Create a new directory for your Halo installation and create a docker-compose.yml file:

docker-compose.yml

version: '3.8'

services:
  halo:
    image: halohub/halo:2.22
    container_name: halo
    restart: always
    ports:
      - "8090:8090"
    volumes:
      - ./data:/root/.halo2
    environment:
      - TZ=America/New_York

Start Halo

docker compose up -d

View logs

docker compose logs -f halo

Docker Compose with MySQL

For production environments, we recommend using an external database like MySQL:

version: '3.8'

services:
  halo:
    image: halohub/halo:2.22
    container_name: halo
    restart: always
    depends_on:
      mysql:
        condition: service_healthy
    ports:
      - "8090:8090"
    volumes:
      - ./data:/root/.halo2
    environment:
      - TZ=America/New_York
    command:
      - --spring.r2dbc.url=r2dbc:pool:mysql://mysql:3306/halo
      - --spring.r2dbc.username=halo
      - --spring.r2dbc.password=your_secure_password
      - --spring.sql.init.platform=mysql

  mysql:
    image: mysql:8.1.0
    container_name: halo-mysql
    restart: always
    command:
      - --default-authentication-plugin=caching_sha2_password
      - --character-set-server=utf8mb4
      - --collation-server=utf8mb4_general_ci
      - --explicit_defaults_for_timestamp=true
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "127.0.0.1", "--silent"]
      interval: 10s
      timeout: 5s
      retries: 5
    ports:
      - "3306:3306"
    volumes:
      - ./mysql:/var/lib/mysql
    environment:
      - MYSQL_ROOT_PASSWORD=your_root_password
      - MYSQL_DATABASE=halo
      - MYSQL_USER=halo
      - MYSQL_PASSWORD=your_secure_password

Replace your_secure_password and your_root_password with strong, unique passwords.

To deploy:

docker compose up -d

Database Configuration Options

Halo supports multiple databases. Configure the connection using command-line arguments:

Database	Connection String Format
H2 (default)	`r2dbc:h2:file:///${halo.work-dir}/db/halo-next?MODE=MySQL&DB_CLOSE_ON_EXIT=FALSE`
MySQL	`r2dbc:pool:mysql://host:3306/database`
MariaDB	`r2dbc:pool:mariadb://host:3306/database`
PostgreSQL	`r2dbc:pool:postgresql://host:5432/database`

1Panel Installation (Recommended for Production)

1Panel is an open-source Linux server management panel that makes Halo deployment much easier. It provides:

One-click Halo installation
Automatic reverse proxy configuration with Nginx
SSL certificate management (Let’s Encrypt integration)
Automated backup scheduling
Easy upgrade management

This is the recommended method for production deployments, especially if you’re not familiar with server administration.

Install 1Panel

Install 1Panel on your Linux server by following the 1Panel installation guide
Access the 1Panel web interface
Navigate to the App Store
Search for “Halo” and click Install
Follow the installation wizard to configure:
- Domain name
- SSL certificate (automatic via Let’s Encrypt)
- Database settings
- Backup schedule

For detailed instructions, refer to the official 1Panel Halo deployment documentation.

Configuration

Application Configuration

Halo’s configuration is stored in the working directory (~/.halo2 by default). Key configuration files:

application.yaml: Main application configuration
db/: Database files (if using H2)
themes/: Installed themes
plugins/: Installed plugins
upload/: Uploaded media files

Port Configuration

To change the default port (8090), you can: Using environment variables:

docker run -d \
  --name halo \
  -p 8080:8080 \
  -v ~/.halo2:/root/.halo2 \
  halohub/halo:2.22 \
  --server.port=8080

In docker-compose.yml:

services:
  halo:
    command:
      - --server.port=8080
    ports:
      - "8080:8080"

Memory Configuration

For better performance, adjust JVM memory settings:

-e JVM_OPTS="-Xmx1g -Xms512m"

-Xmx: Maximum heap size
-Xms: Initial heap size

Allocate memory based on your expected traffic and content volume. A typical small to medium site runs well with 512MB-1GB.

Post-Installation Steps

Complete setup wizard

Navigate to your Halo URL and complete the initial setup wizard to create your admin account.

Configure site settings

Access the admin console at /console and configure:

Site title and description
SEO settings
Comment system
Social media links

Install a theme

Visit the theme marketplace in the admin console to browse and install a theme that matches your vision.

Set up backups

Configure regular backups of your data directory:

/root/.halo2 (or your configured work directory)
Database files (if using external database)

If using 1Panel, you can configure automated backups through the panel interface.

Configure reverse proxy (optional)

For production, set up a reverse proxy like Nginx to:

Enable HTTPS with SSL certificates
Improve performance with caching
Use a custom domain

1Panel handles this automatically, or you can configure Nginx manually.

Updating Halo

Docker Update

docker stop halo
docker rm halo
docker pull halohub/halo:latest
docker run -d \
  --name halo \
  -p 8090:8090 \
  -v ~/.halo2:/root/.halo2 \
  halohub/halo:latest

Docker Compose Update

docker compose down
docker compose pull
docker compose up -d

Always backup your data directory before updating Halo.

Troubleshooting

Container won’t start

Check Docker logs:
```
docker logs halo
```
Verify port availability:
```
lsof -i :8090
```
Check disk space:
```
df -h
```

Database connection errors

Verify database container is healthy: docker ps
Check database credentials in your configuration
Ensure database service starts before Halo (use depends_on in compose)

Performance issues

Increase JVM memory allocation
Use an external database instead of H2
Enable caching in your reverse proxy
Monitor resource usage: docker stats halo

Getting Help

If you encounter issues during installation:

Review the official Halo documentation
Check the community forum for similar issues
Join the Telegram channel for community support
Report bugs on GitHub

Next Steps

Theme Customization

Learn how to customize your site’s appearance with themes

Plugin Development

Extend Halo’s functionality by developing custom plugins

API Integration

Integrate Halo with external services using the REST API

Performance Optimization

Optimize your Halo installation for better performance

Get Started

Core Concepts

User Guide

Deployment

​Installation Guide

​Installation Methods

Docker

Docker Compose

1Panel

Manual Installation

​System Requirements

​Minimum Requirements

​Software Requirements

​Docker Installation

​Basic Docker Deployment

​Docker with Environment Variables

​Docker Compose Installation

​Basic Docker Compose Setup

​Docker Compose with MySQL

​Database Configuration Options

​1Panel Installation (Recommended for Production)

​Install 1Panel

​Configuration

​Application Configuration

​Port Configuration

​Memory Configuration

​Post-Installation Steps

​Updating Halo

​Docker Update

​Docker Compose Update

​Troubleshooting

​Container won’t start

​Database connection errors

​Performance issues

​Getting Help

​Next Steps

Theme Customization

Plugin Development

API Integration

Performance Optimization

Build docs developers (and LLMs) love

Installation Guide

Installation Methods

System Requirements

Minimum Requirements

Software Requirements

Docker Installation

Basic Docker Deployment

Docker with Environment Variables

Docker Compose Installation

Basic Docker Compose Setup

Docker Compose with MySQL

Database Configuration Options

1Panel Installation (Recommended for Production)

Install 1Panel

Configuration

Application Configuration

Port Configuration

Memory Configuration

Post-Installation Steps

Updating Halo

Docker Update

Docker Compose Update

Troubleshooting

Container won’t start

Database connection errors

Performance issues

Getting Help

Next Steps