Powerful and easy-to-use open source website building tool Halo

features

Pluggable Architecture

Halo adopts a pluggable architecture, with low coupling between functional modules and increased flexibility. Support users to install and uninstall plug-ins on demand, and the operation is convenient. At the same time, a plug-in development interface is provided to ensure high scalability and maintainability.
☑ Support for installing and uninstalling plug-ins at runtime
☑ More convenient integration of three-party platforms
☑ Unified configurable setting form
☑ Support for custom models and automatically generate RESTful API

Feature-rich theme mechanism

Halo provides a complete theme template mechanism for building the front-end interface. This means that users can choose different types of theme templates to customize their site appearance according to their preferences.
☑ Dynamically switch theme templates
☑ Support real-time editing and preview effects
☑ Multilingual support
☑ Work with plug-ins to achieve more functions

editor

Halo's rich text editor provides convenient and rich functions, including adding elements such as titles, paragraphs, references, lists, code blocks, etc., and supports functions such as setting style attributes, uploading images, and inserting videos. These tools make your article creation more convenient and lively.
☑ Complete rich text format support
☑ Support dragging and pasting pictures to upload
☑ Support extending the editor through plug-ins

more features

Code open source
Halo's project code is open source on GitHub and is under active maintenance. Up to now, 109 versions have been released. You can also submit your questions or participate in code contributions on it.

Easy to deploy
It is recommended to use Docker to deploy Halo, which is easy to upgrade and avoids various environmental dependencies. Unified management of application data in the working directory can also be easily backed up and migrated.

The plug-in mechanism
supports adding new functions to the system when the plug-in is running, while keeping Halo itself simple and lightweight. This flexible plug-in mechanism allows users to freely expand the functions of Halo according to their own needs, helping users to realize imaginative sites.

The template mechanism
supports functions such as custom configuration, theme preview, and multiple languages. This flexible template system allows users to customize configurations according to their own needs, bringing a more personalized appearance and interactive experience to the website.

Attachment management
supports multiple storage strategies, and supports external storage location expansion through plug-ins, allowing users to upload, view and manage attachments more flexibly.

Search engine
Built-in full-text search engine, supports keywords to search articles and page content. At the same time, it supports the expansion of external search engines through plug-ins, so that users can choose and expand freely according to their needs.

deploy

rapid deployment

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

Environmental requirements

Hardware Configuration

提示
If you want to use a server to deploy Halo, you need to note that Halo currently does not support cloud virtual hosts on the market, please use a cloud server or VPS.
CPU
has no special requirements. Currently our Docker image also supports multiple platforms.
Memory
In order to get a better experience, we recommend configuring at least 1G of RAM.
There is no special requirement for the disk
. In theory, if you do not upload a large number of attachments to the server, Halo does not require a high disk capacity. But we recommend servers with SSD hard drives, which can run Halo faster.
Network
Halo must be used when the external network is unblocked, otherwise it will cause abnormal page

Software Environment

Halo can theoretically run on any platform that supports Docker and Java.
Docker
must have a Docker environment installed in the operating environment. Currently, the default installation and operation methods of Halo use containers.
JRE (optional)
Currently, the default and recommended installation method of Halo is to run in a Docker container, and the way to run with a jar package requires the user to build the jar package by himself.
Info:
The current version (2.0) requires JRE 17, OpenJDK 17 is recommended.

PostgreSQL (optional)
can also use the H2 Database that comes with the system without installation. However, it is not recommended to use H2 Database in a production environment.

Web server (optional)
If you are deploying in a production environment, you probably need to bind domain names. At this time, we recommend using web servers such as Nginx and Caddy for reverse proxy. But it should be noted that currently Halo does not support proxying to subdirectories (eg: halo.run/blog).

Wget (optional)
In the following documents, we will use wget as an example to download the required files, so please make sure the server has installed this package. Of course, the download file does not limit the tool, if you are familiar with other tools, you can ignore it.

VIM (optional)
In subsequent documents, we will use vim as an example to modify some necessary configuration files, so please also ensure that the server has installed this package. Currently, there are no restrictions on tools for modifying documents. If you are familiar with other editing software, you can ignore it.

browser support

1. User front desk: It depends on the support of the theme. Since the current comment module is developed with Vuejs, the comment area cannot be displayed normally in some browsers that Vuejs does not support.
2. Management background: Support the current common modern browsers, depending on the support of the Vuejs framework.

Glossary

~ (symbol)
represents the user directory under the current system.
Image
Refers to the Docker image produced by the Halo build. The user launches the Halo application through this image.
Working directory refers to the working directory that Halo depends on. When Halo is running , a folder
will be generated under the current user directory of the system . The absolute path is ~/.halo2. .halo2Since this working directory is fixed, the running package mentioned above does not limit the storage location, which usually contains the following directories or files:
☑ db: stores the physical file of H2 Database, if you use other databases, it will not exist this directory.
☑ themes: It contains the themes installed by the user.
☑ plugins: It contains the plugins installed by the user.
☑ attachments: attachment directory.
☑ logs: run log directory.
☑ application.yaml: configuration file.
Themes
A resource bundle containing various site page templates. The content and style that the user browses when visiting the Halo site are determined by the theme configured and used by the Halo management terminal.
Plugins
Packages that extend the functionality of Halo. Plug-ins are independent of the Halo core application and can be installed, upgraded, and uninstalled separately.

Use Docker-Compose

Note
Currently Halo 2 has not updated the latest tag image of Docker, mainly because Halo 2 is not compatible with version 1.x to prevent users from misuse. We recommend using a fixed version tag, such as halohub/halo:2.9 or halohub/halo:2.9.0.
☑ halohub/halo:2.9: Indicates the latest 2.9.x version, that is, the halohub/halo:2.9 image will be updated at the same time when the patch version is released.
☑ halohub/halo:2.9.0: indicates a specific version.
Subsequent documents use halohub/halo:2.9as an example .

1. Create a folder anywhere in the system. This document uses ~/halo as an example.

mkdir ~/halo && cd ~/halo

2. Create docker-compose.yaml

This document provides Docker Compose configuration files for two scenarios, please choose one according to your needs.

Create an instance of Halo + PostgreSQL:

version: "3"

services:
  halo:
    image: halohub/halo:2.9
    container_name: halo
    restart: on-failure:3
    depends_on:
      halodb:
        condition: service_healthy
    networks:
      halo_network:
    volumes:
      - ./:/root/.halo2
    ports:
      - "8090:8090"
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8090/actuator/health/readiness"]
      interval: 30s
      timeout: 5s
      retries: 5
      start_period: 30s          
    command:
      - --spring.r2dbc.url=r2dbc:pool:postgresql://halodb/halo
      - --spring.r2dbc.username=halo
      # PostgreSQL 的密码，请保证与下方 POSTGRES_PASSWORD 的变量值一致。
      - --spring.r2dbc.password=openpostgresql
      - --spring.sql.init.platform=postgresql
      # 外部访问地址，请根据实际需要修改
      - --halo.external-url=http://localhost:8090/
  halodb:
    image: postgres:latest
    container_name: halodb
    restart: on-failure:3
    networks:
      halo_network:
    volumes:
      - ./db:/var/lib/postgresql/data
    ports:
      - "5432:5432"
    healthcheck:
      test: [ "CMD", "pg_isready" ]
      interval: 10s
      timeout: 5s
      retries: 5
    environment:
      - POSTGRES_PASSWORD=openpostgresql
      - POSTGRES_USER=halo
      - POSTGRES_DB=halo
      - PGUSER=halo

networks:
  halo_network:

Create an instance of Halo + MySQL:

version: "3"

services:
  halo:
    image: halohub/halo:2.9
    container_name: halo
    restart: on-failure:3
    depends_on:
      halodb:
        condition: service_healthy
    networks:
      halo_network:
    volumes:
      - ./:/root/.halo2
    ports:
      - "8090:8090"
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8090/actuator/health/readiness"]
      interval: 30s
      timeout: 5s
      retries: 5
      start_period: 30s
    command:
      - --spring.r2dbc.url=r2dbc:pool:mysql://halodb:3306/halo
      - --spring.r2dbc.username=root
      # MySQL 的密码，请保证与下方 MYSQL_ROOT_PASSWORD 的变量值一致。
      - --spring.r2dbc.password=o#DwN&JSa56
      - --spring.sql.init.platform=mysql
      # 外部访问地址，请根据实际需要修改
      - --halo.external-url=http://localhost:8090/

  halodb:
    image: mysql:8.0.31
    container_name: halodb
    restart: on-failure:3
    networks:
      halo_network:
    command: 
      - --default-authentication-plugin=mysql_native_password
      - --character-set-server=utf8mb4
      - --collation-server=utf8mb4_general_ci
      - --explicit_defaults_for_timestamp=true
    volumes:
      - ./mysql:/var/lib/mysql
      - ./mysqlBackup:/data/mysqlBackup
    ports:
      - "3306:3306"
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "127.0.0.1", "--silent"]
      interval: 3s
      retries: 5
      start_period: 30s
    environment:
      # 请修改此密码，并对应修改上方 Halo 服务的 SPRING_R2DBC_PASSWORD 变量值
      - MYSQL_ROOT_PASSWORD=o#DwN&JSa56
      - MYSQL_DATABASE=halo

networks:
  halo_network:

Only create a Halo instance (use the default H2 database, not recommended for production environments, but recommended for experience and testing):

version: "3"

services:
  halo:
    image: halohub/halo:2.9
    container_name: halo
    restart: on-failure:3
    volumes:
      - ./:/root/.halo2
    ports:
      - "8090:8090"
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8090/actuator/health/readiness"]
      interval: 30s
      timeout: 5s
      retries: 5
      start_period: 30s          
    command:
      # 外部访问地址，请根据实际需要修改
      - --halo.external-url=http://localhost:8090/

Only create a Halo instance (use an existing external database, MySQL as an example):

version: "3"

services:
  halo:
    image: halohub/halo:2.9
    container_name: halo
    restart: on-failure:3
    network_mode: "host"
    volumes:
      - ./:/root/.halo2
    command:
      # 修改为自己已有的 MySQL 配置
      - --spring.r2dbc.url=r2dbc:pool:mysql://localhost:3306/halo
      - --spring.r2dbc.username=root
      - --spring.r2dbc.password=
      - --spring.sql.init.platform=mysql
      # 外部访问地址，请根据实际需要修改
      - --halo.external-url=http://localhost:8090/
      # 端口号 默认8090
      - --server.port=8090

参数详解：

parameter name	describe
spring.r2dbc.url	Database connection address, please refer to the following for details数据库配置
spring.r2dbc.username	database username
spring.r2dbc.password	database password
spring.sql.init.platform	Database platform name, support postgresql, mysql,h2
halo.external-url	External access link, if it needs to be accessed on the public network, it needs to be configured as the actual access address
halo.cache.page.disabled	Whether to disable page caching, the default is disabled, if you need page caching, you can manually add this configuration and set it to false. After the cache is enabled, it will not go through the cache when you log in, and the inactive cache will be cleared for one hour by default, or you can manually clear the cache in the quick access of the Console dashboard.

数据库配置：

link method	link address format	spring.sql.init.platform
PostgreSQL	r2dbc:pool:postgresql://{HOST}:{PORT}/{DATABASE}	postgresql
MySQL	r2dbc:pool:mysql://{HOST}:{PORT}/{DATABASE}	mysql
MariaDB	r2dbc:pool:mariadb://{HOST}:{PORT}/{DATABASE}	mysql
H2 Database	r2dbc:h2:file:///${halo.work-dir}/db/halo-next?MODE=MySQL&DB_CLOSE_ON_EXIT=FALSE	h2

3. Start the Halo service

docker-compose up -d

View logs in real time:

docker-compose logs -f

4. Use a browser to access /console to enter the Halo management page, and it will enter the initialization page when it is started for the first time.

Tip:
If you need to configure domain name access, it is recommended to configure the reverse proxy and domain name resolution before initializing. If http://ip:端口号you cannot access through the form, please go to the backend of the server manufacturer to add the running port number to the security group. If the server uses a Linux panel, please check whether there is a security group configuration in this Linux panel. You need to add the port number to the security group as well. Group.

Update container group

1. Stop the running container group

cd ~/halo && docker-compose down

2. Backup data (important)

It should be noted that the halo.archive file name does not have to be named according to this document, this is just an example.

cp -r ~/halo ~/halo.archive

3. Update the Halo service
Modify the image version configured in docker-compose.yaml.

services:
  halo:
    image: halohub/halo:2.9
    container_name: halo
docker-compose pull halo
docker-compose up -d

reverse proxy

For more information, please visit https://docs.halo.run/category/%E5%85%B6%E4%BB%96%E6%8C%87%E5%8D%97 Introduction to
Nginx As the name suggests, Nginx Proxy Manager is a Nginx's proxy manager, its biggest feature is simplicity and convenience. Even a small partner without Nginx foundation can easily use it to complete the reverse proxy operation, and because of the built-in panel, the operation is extremely simple, and it is very suitable for use with applications built with docker. The Nginx Proxy Manager background can also apply for an SSL certificate with one click, and it will automatically renew, which is convenient and worry-free.

upstream halo {
    
    
  server 127.0.0.1:8090;
}
server {
    
    
  listen 80;
  listen [::]:80;
  server_name www.yourdomain.com;
  client_max_body_size 1024m;
  location / {
    
    
    proxy_pass http://halo;
    proxy_set_header HOST $host;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  }
}

Caddy 2

www.yourdomain.com

encode gzip

reverse_proxy 127.0.0.1:8090

Traefik
Traefik is an open source reverse proxy and load balancing tool that monitors backend changes and automatically updates service configurations.
The biggest difference between it and the traditional reverse proxy is that it supports declarative dynamic routing rules, which greatly simplifies the configuration of gateway rules. And there are many practical features, such as: health check, multi-instance load balancing, automatic issuance, verification and renewal of Let's Encrypt certificates, etc.
Update the configuration of the halo container group
1. networksIntroduce the existing network traefik(this network needs to be created in advance)
2. services.halo.networksAdd the network traefik
3. Change the external address to your domain name
4. Declare routing rules and enable TLS

version: "3.8"

networks:
  traefik:
    external: true
  halo:

services:
  halo:
    image: halohub/halo:2.9
    container_name: halo
    restart: on-failure:3
    volumes:
      - ./:/root/.halo2
    networks:
      - traefik
      - halo
    command:
      # 外部访问地址，请根据实际需要修改
      - --halo.external-url=https://yourdomain.com
    labels:
      traefik.enable: "true"
      traefik.docker.network: traefik
      traefik.http.routers.halo.rule: Host(`yourdomain.com`)
      traefik.http.routers.halo.tls: "true"
      traefik.http.routers.halo.tls.certresolver: myresolver
      traefik.http.services.halo.loadbalancer.server.port: 8090

Any limitation starts from your own heart.