Halo User Guide

Halo is a powerful, easy-to-use open-source website building tool. With a single self-hosted application you can run a personal blog, a knowledge base, a documentation site, a company homepage, or any content-driven website. This guide shows you how to install Halo, set it up, and use every part of the management console to publish and manage your content.

Note

This guide covers the open-source Halo Community Edition (licensed under GPL-3.0). The application is bilingual; its administration console ships with multiple languages and defaults based on your browser. Commercial "Pro" and "Commerce" editions add features (mobile app, AI site building, online store) that are not part of this open-source project and are not documented here.

1. What Is Halo?

Halo is a self-contained server application. You run one process (or one container), point your browser at it, and manage your whole website from a built-in admin console. Visitors see your public site; you manage everything from a private dashboard.

At a glance, Halo gives you:

• Content management — posts, single pages, categories, tags, and a moderated comment system, all edited in a rich WYSIWYG editor.
• A theme system — swap the entire look of your public site by installing a theme; customize it through a settings form, no code required.
• A plugin system — extend functionality (comment widgets, search, sitemaps, RSS feeds, syntax highlighting, and more) by installing plugins.
• Attachment (media) management — upload, organize, and serve images and files, with pluggable storage backends.
• User and permission management — invite users, assign roles, and control exactly what each person can do.
• Account security — two-factor authentication, OAuth2 social login, personal access tokens, and login auditing.
• Full-site backup and restore — export your entire site (database + working files) to a single archive and restore it elsewhere.

Tip

Halo stores everything it needs — database, uploaded files, themes, plugins, logs — under a single working directory (by default ~/.halo2). Back up that one directory (plus a database dump if you use an external database) and you have backed up your entire site.

Editions at a glance

2. Quick Start (5 Minutes with Docker)

The fastest way to try Halo is Docker. This command starts a fully working Halo on port 8090, using a file-based H2 database so you need nothing else installed:

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

Unable to find image 'halohub/halo:2.24' locally
2.24: Pulling from halohub/halo
...
Status: Downloaded newer image for halohub/halo:2.24
a1b2c3d4e5f6...   (the container ID)

What each part does:

Now open a browser:

• Public site: http://localhost:8090
• Admin console: http://localhost:8090/console

On first launch Halo shows a setup wizard at /console. Fill in your site title, the administrator username, password, and email, and submit. You are then taken to the dashboard.

Important

The Quick Start above uses the built-in H2 database, which is perfect for evaluation but not recommended for production. For a real site, use PostgreSQL or MySQL and put Halo behind a reverse proxy with HTTPS. See Section 4 (Installation) and the Admin Guide.

Warning

The publicly hosted demo (https://demo.halocms.site, console https://demo.halocms.site/console) is reset periodically and shared with everyone. Never store anything private there.

Try it without installing anything

If you do not have Docker locally, the project offers one-click cloud sandboxes via Gitpod and ClawCloud Run (links are on the project's GitHub page). These spin up a temporary Halo for experimentation only.

3. Requirements

Halo is distributed as a Docker image and as an executable Java archive (JAR). Pick whichever fits your environment.

Database options (choose one):

Note

Halo connects to databases reactively using R2DBC drivers (not the traditional JDBC). The official image ships drivers for H2, PostgreSQL, MySQL, and MariaDB, so no extra driver installation is required.

Network:

• Halo listens on TCP port 8090 by default.
• For a public site you will typically run a reverse proxy (Nginx, Caddy, Traefik, or a panel like 1Panel) in front of Halo to terminate HTTPS.

4. Installation

4.1 Docker (single container)

The Quick Start command in Section 2 is a complete single-container install. For anything beyond evaluation, pin a specific patch version and set your external URL and timezone.

Linux / macOS

docker run -d \
  --name halo \
  -p 8090:8090 \
  -v ~/.halo2:/root/.halo2 \
  -e TZ=Asia/Shanghai \
  halohub/halo:2.24

Windows (PowerShell)

docker run -d `
  --name halo `
  -p 8090:8090 `
  -v ${HOME}\.halo2:/root/.halo2 `
  -e TZ=Asia/Shanghai `
  halohub/halo:2.24

Tip

The container's default timezone is Asia/Shanghai. Override it with -e TZ=... (for example -e TZ=America/Phoenix or -e TZ=UTC) so timestamps on posts and logs match your locale.

4.2 Docker Compose (with PostgreSQL)

For production, run Halo and a real database together with Docker Compose. Create a docker-compose.yaml:

services:
  halo:
    image: halohub/halo:2.24
    restart: on-failure:3
    depends_on:
      halodb:
        condition: service_healthy
    networks:
      halo_network:
    volumes:
      - ./halo2:/root/.halo2
    ports:
      - "8090:8090"
    environment:
      - JVM_OPTS=-Xmx256m -Xms256m
    command:
      - --spring.r2dbc.url=r2dbc:pool:postgresql://halodb/halo
      - --spring.r2dbc.username=halo
      - --spring.r2dbc.password=openpostgresql
      - --spring.sql.init.platform=postgresql
      - --halo.external-url=http://localhost:8090/

  halodb:
    image: postgres:15.4
    restart: on-failure:3
    networks:
      halo_network:
    volumes:
      - ./halodb:/var/lib/postgresql/data
    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:

Start it:

docker compose up -d

[+] Running 3/3
 ✔ Network halo_halo_network  Created
 ✔ Container halo-halodb-1     Healthy
 ✔ Container halo-halo-1       Started

Important

Set --halo.external-url to the real public address of your site (for example https://blog.example.com/). Halo uses it to build absolute links in feeds, sitemaps, social-share metadata, and emails. Getting it wrong causes broken links in those places.

The three command-line arguments that point Halo at PostgreSQL are the key ones to adapt for MySQL/MariaDB — see the table below.

4.3 Executable JAR

If you prefer not to use Docker, run the JAR directly on a host with Java 21:

java -jar halo.jar

  .   ____          _            __ _ _
 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
  '  |____| .__|_| |_|_| |_\__, | / / / /
 =========|_|==============|___/=/_/_/_/
 :: Halo ::

Pass configuration as --key=value arguments, exactly like the Compose command: entries:

java -jar halo.jar \
  --halo.work-dir=/opt/halo/data \
  --halo.external-url=https://blog.example.com/ \
  --spring.r2dbc.url=r2dbc:pool:postgresql://localhost/halo \
  --spring.r2dbc.username=halo \
  --spring.r2dbc.password=secret \
  --spring.sql.init.platform=postgresql

Note

Halo is a standard Spring Boot application. Any setting in this guide can be supplied three equivalent ways: a --flag=value command-line argument, an environment variable (HALO_EXTERNAL_URL=...), or a line in a application.yaml config file placed in the working directory. Command-line arguments win over environment variables, which win over the config file.

4.4 First-run setup wizard

However you install, the first time you open /console Halo presents a setup form:

• [ ] Site title — the name shown in the browser tab and theme header.
• [ ] Username — your administrator account login name.
• [ ] Password — choose a strong password; this account has full control.
• [ ] Email — used for notifications and password recovery.

Submit the form to create your admin account and finish initialization. You can change all of these later under System → Settings and System → Users.

5. The Console at a Glance

After logging in at /console, you land on the Dashboard. The left sidebar groups every feature into five areas:

There is also a separate User Center at /uc — a self-service area where any logged-in user (not just admins) manages their own profile, security, personal posts, and notifications. See Section 13.

Tip

The sidebar is dynamic. Installing a plugin can add new menu entries and even new menu groups. If a menu item is missing, your account's role may not grant permission to see it — ask an administrator.

6. Writing and Managing Posts

Posts are your primary, time-ordered content (blog articles, news, announcements).

6.1 Create a post

1. Go to Content → Posts.
2. Click New Post (or New Page in the Pages section).
3. Write in the editor. The default editor is a rich-text WYSIWYG editor built on Tiptap/ProseMirror; you can also switch to a Markdown-oriented editing experience if a Markdown editor plugin is installed.
4. Open the settings panel (usually a side drawer) to set the post's metadata before publishing.

The editor toolbar supports a full range of formatting because Halo bundles these editor extensions:

Tip

Type / in the editor to open the commands menu and insert images, tables, code blocks, and more without leaving the keyboard.

6.2 Post settings

In the post settings panel you control how the post is stored, addressed, and displayed:

6.3 Drafts, publishing, and revisions

• Saving without publishing keeps the post as a draft (not visible to the public).
• Publish makes it live. Unpublish returns it to draft without deleting it.
• Halo keeps snapshots of content as you edit, so you can review and roll back to earlier versions of a post.
• Deleting a post moves it to the Recycle Bin first; deleting from the bin is permanent.

Note

Every post separates its metadata (title, slug, categories) from its content snapshots. This is why you can change a post's settings without creating a new content revision, and revert content without losing settings.

7. Pages, Categories, and Tags

7.1 Single pages

Single pages (under Content → Pages) are standalone, non-time-ordered content such as "About", "Contact", or a landing page. They use the same editor and settings model as posts but are not listed in your blog feed or organized by category.

7.2 Categories

Categories (Content → Categories) organize posts hierarchically (a category can have child categories). Each category has:

• A name and slug (used in the URL).
• An optional description and cover.
• A template override (themes may provide alternate layouts per category).

Reorder and re-nest categories by dragging them in the tree view.

7.3 Tags

Tags (Content → Tags) are a flat, lightweight way to label posts across categories. Create a tag, give it a name, slug, and optional color, then apply it from any post's settings panel.

Tip

Use categories for your site's main structure (a handful of broad sections) and tags for cross-cutting topics (many fine-grained labels). Themes typically render category pages prominently and tags as a cloud or filter.

8. Comments and Moderation

Halo has a built-in, moderated comment system that works across posts, pages, and other comment-enabled content.

Manage comments under Content → Comments:

• See all comments and their threaded replies in one place.
• Approve pending comments to make them public, or leave moderation on so nothing appears until you approve it.
• Reply to a commenter directly from the console.
• Delete spam or unwanted comments.

Note

The front-end comment box that visitors see is usually provided by the comment widget plugin (bundled by default). The console section above manages the data regardless of which front-end widget renders it.

Important

Comment creation is rate-limited by default (10 comments per minute per source) to reduce spam and abuse. Legitimate users are unaffected; automated flooding is throttled.

9. Attachments (Media Library)

The attachment system (Content → Attachments) is Halo's media library for images, documents, and other files.

9.1 Uploading

• Drag-and-drop files, or click to browse.
• Uploads can also happen inline while editing a post (for example pasting or dropping an image into the editor).
• Files are grouped, searchable, and reusable across posts.

9.2 Storage policies

Where files physically live is controlled by a storage policy. Out of the box Halo stores attachments in its working directory (local storage). By installing a storage plugin you can add policies that send uploads to object storage (S3-compatible services, etc.). Each attachment is associated with the policy it was uploaded under.

9.3 Thumbnails

Halo automatically generates thumbnails for images so themes can serve appropriately sized versions. Thumbnail generation can be tuned (quality, concurrency) or disabled by an administrator — see the Admin Guide's configuration reference.

Tip

A "Default Storage Policy for User Avatars" and client-side image compression before upload are frequently requested enhancements tracked by the community. If you need object storage today, install the appropriate storage plugin from the application market.

10. Themes: Changing How Your Site Looks

A theme controls the entire appearance of your public site. Manage themes under Interface → Themes.

10.1 Install and activate

1. Go to Interface → Themes.
2. Install a theme by uploading its package (a .zip) or installing from a URL / the application market.
3. Click Activate to make it your live theme.

A fresh Halo ships with a default theme (internally the "earth" theme) so your site is never blank.

10.2 Customize a theme

Most themes expose a settings form — Halo renders it from the theme's own definition, so you configure colors, layout options, social links, and more through form fields rather than editing code. Themes can also define:

• Custom templates for specific posts, pages, categories, or tags.
• Menu integration (see below).

Note

Themes are built with Thymeleaf server-side templates. You do not need to know Thymeleaf to use a theme — only to build one (covered in the Admin Guide and the developer documentation).

10.3 Menus

Navigation menus are managed under Interface → Menus:

• Create one or more menus (for example a header menu and a footer menu).
• Add menu items that link to posts, pages, categories, tags, or arbitrary URLs.
• Drag items to reorder and nest them.

Your active theme decides where each menu appears.

11. Plugins: Extending Halo

Plugins add features without changing Halo's core. Manage them under System → Plugins.

11.1 Install, enable, configure

1. Go to System → Plugins.
2. Install a plugin by uploading its .jar package or installing from the application market.
3. Enable it. Some plugins add new console menu items, new editor tools, new storage policies, or new front-end widgets.
4. If the plugin has settings, a configuration tab appears — fill in the form and save.

11.2 Plugins bundled by default

A standard Halo build downloads and includes several first-party plugins so common needs work out of the box:

Tip

Browse more themes and plugins in the official application market (halo.run/store/apps) and the community-curated awesome-halo list. Plugins can be enabled and disabled at any time without reinstalling.

Caution

Only install themes and plugins from sources you trust. A plugin runs inside your Halo server with broad access. Disable or uninstall anything you do not recognize.

12. Users, Roles, and Permissions

12.1 Users

Manage accounts under System → Users:

• Create users and set their display name, username, email, and avatar.
• Assign roles to grant permissions.
• Disable or delete accounts.

12.2 Roles

Halo uses role-based access control (RBAC). A role is a named bundle of permissions (for example view posts, manage attachments, manage users). Manage roles under System → Roles:

• Use the built-in roles (such as a super administrator role with full access) or create custom roles.
• Assign one or more roles to each user; their effective permissions are the union.

Important

The super administrator role has unrestricted access, including sensitive system operations. Grant it sparingly. For everyday editors, create a limited role that grants only content permissions.

12.3 Authentication providers

Under System → Auth Providers you can enable additional sign-in methods (for example OAuth2 social login) supplied by plugins, alongside the built-in username/password login.

13. The User Center (/uc)

Separate from the admin console, the User Center at /uc is where any logged-in user manages their own account — useful when you have contributors who should not see the full admin console.

The User Center includes:

14. Securing Your Account

Halo includes several account-security features you can use right away from the User Center (/uc → Security).

14.1 Two-factor authentication (2FA)

Halo supports TOTP two-factor authentication (compatible with Google Authenticator, Authy, 1Password, etc.):

1. Go to /uc → Security → Two-factor authentication.
2. Scan the displayed QR code with your authenticator app.
3. Enter the 6-digit code to confirm and enable 2FA.

After enabling, logins require your password plus the current 6-digit code.

Warning

Save your recovery information when enabling 2FA. If you lose your authenticator device and have no recovery method, an administrator may need to intervene to restore access.

14.2 Personal access tokens (PAT)

For scripts and integrations, create a personal access token instead of using your password:

1. Go to /uc → Security → Personal access tokens.
2. Create a token, give it a name and scope, and copy it immediately (it is shown only once).
3. Use it as a bearer token when calling Halo's API.

Caution

A personal access token carries your permissions. Treat it like a password, scope it as narrowly as possible, and revoke it the moment it is no longer needed.

14.3 "Remember me" and login protection

• Remember me keeps you signed in across browser restarts; the token is valid for 14 days by default and rotates automatically for safety.
• Login attempts are rate-limited (3 attempts per minute by default) to slow down password-guessing attacks. If you are temporarily blocked after several failures, wait a minute and try again.

15. Backing Up and Restoring Your Site

Halo can export your entire site — database content and working-directory files (themes, plugins, attachments) — into a single archive.

15.1 Create a backup

1. Go to System → Backup.
2. Click Create backup. Halo runs the backup asynchronously and reports progress; for large sites this can take a while.
3. When it finishes, download the .zip archive.

Backups are written to ${halo.work-dir}/backups/ on the server (for example ~/.halo2/backups/halo-full-backup-<timestamp>.zip).

15.2 Restore a backup

1. Go to System → Backup → Restore.
2. Upload a previously created backup archive.
3. Halo restores the database records and working-directory files.

Important

Always take a fresh backup before restoring over an existing site. Restore replaces data, and some timestamps (such as creation times) may be reset to the restore time.

Tip

Because a full backup is database-agnostic, it is the supported way to migrate between databases — for example from the default H2 to PostgreSQL — without worrying about SQL dialect differences. Back up on the old database, point a fresh Halo at the new database, and restore.

16. Common Workflows

16.1 Publish your first blog post

• [ ] Open /console and log in.
• [ ] Go to Content → Categories and create a category (e.g. "Blog").
• [ ] Go to Content → Posts → New Post.
• [ ] Write your content, set the title, slug, and category in the settings panel.
• [ ] Click Publish.
• [ ] Visit your public site to see it live.

16.2 Set up a custom domain with HTTPS

• [ ] Point your domain's DNS at your server.
• [ ] Put a reverse proxy (Nginx, Caddy, Traefik, or 1Panel) in front of Halo on port 8090.
• [ ] Obtain a TLS certificate (Let's Encrypt) at the proxy.
• [ ] Set --halo.external-url=https://yourdomain.com/ so Halo builds correct absolute links.
• [ ] Restart Halo and verify links in feeds and sitemaps are correct.

16.3 Add search, RSS, and a sitemap

• [ ] Go to System → Plugins.
• [ ] Ensure the Search widget, Feed, and Sitemap plugins are installed and enabled.
• [ ] Confirm your theme places the search box (Interface → Themes settings).
• [ ] Visit /sitemap.xml and your feed URL to confirm they generate.

16.4 Move your site to a new server

• [ ] On the old server: System → Backup → Create backup, then download the archive.
• [ ] On the new server: install Halo (same major version) pointed at your production database.
• [ ] Open /console, complete setup, then System → Backup → Restore the archive.

17. Troubleshooting

Error: External URL is required when property use-absolute-permalink is set to true.

Cause: You enabled absolute permalinks but did not set an external URL, so Halo cannot build absolute links.

Solution: Set --halo.external-url=https://yourdomain.com/ (or the HALO_EXTERNAL_URL environment variable) and restart. The URL must be a valid http/https address.

Prevention: Always configure halo.external-url before turning on absolute permalinks.

Error: External URL must be a http or https URL.

Cause: The value of halo.external-url is not a valid HTTP/HTTPS URL (for example a missing scheme or an opaque URI).

Solution: Use a full URL including the scheme and host, e.g. https://blog.example.com/.

Error: Public key location does not exist / Private key location does not exist

Cause: Halo's OAuth2/JWT signing keys could not be found at the configured location.

Solution: Let Halo manage keys in its working directory (the default), or set valid halo.security.oauth2.jwt.public-key-location and ...private-key-location paths that point to existing RSA key files.

Prevention: Do not move or delete files under the working directory's security folder.

Problem: The site loads but I cannot reach /console

Cause: Reverse proxy not forwarding all paths, or you are hitting the wrong port.

Solution: Confirm Halo is listening on 8090 and that your proxy forwards /console, /uc, and /apis/** — not just /. With forward-headers-strategy: native (the default), Halo honors X-Forwarded-* headers from your proxy.

Problem: I was logged out / "too many attempts" on login

Cause: The default login rate limit (3 attempts per minute) tripped.

Solution: Wait about a minute and try again with the correct credentials. If you forgot your password, use the email password-reset flow.

Problem: Uploaded images don't appear or thumbnails are missing

Cause: Storage policy misconfiguration, a full disk, or thumbnail generation disabled.

Solution: Check Content → Attachments that files uploaded successfully, verify free disk space in the working directory, and confirm the active storage policy. An administrator can re-enable thumbnails if they were turned off.

Problem: Data disappeared after restarting the container

Cause: You did not mount a volume, so the container's working directory was ephemeral.

Solution: Always run with -v ~/.halo2:/root/.halo2 (or a named volume). Without it, all data is lost when the container is removed.

Prevention: Treat the working-directory volume as the home of your entire site and back it up.

Problem: Editor loses a character when typing inline code / certain characters

Cause: A known editor edge case reported by the community (see project issues such as inline-code input handling).

Solution: Update to the latest Halo release, which includes ongoing editor fixes. As a workaround, type the surrounding text first and apply inline-code formatting afterward.

Problem: Duplicate notifications after configuring a notifier

Cause: A reported issue where extending a notifier could cause duplicate messages.

Solution: Keep Halo updated; review your notification settings under /uc → Notifications and avoid configuring overlapping notifiers for the same event.

Tip

For deeper operational issues — container logs, database connectivity, performance tuning, health checks — see the Halo Admin Guide, which documents configuration, deployment, and diagnostics in detail.

18. Frequently Asked Questions

Q: Is Halo free? Yes. The Community Edition documented here is fully open source under GPL-3.0 and free to self-host. Paid Pro/Commerce editions exist with additional features but are separate products.

Q: Do I need to know how to code? No. Installing, theming, and managing content are all done through the console and form-based settings. Coding is only needed to build custom themes or plugins.

Q: Which database should I use? H2 for evaluation. For a real site, use PostgreSQL (recommended) or MySQL/MariaDB.

Q: Where is all my data stored? Under the working directory, ~/.halo2 by default (/root/.halo2 inside the container). It holds the H2 database (if used), attachments, themes, plugins, logs, and backups.

Q: How do I back up everything? Use System → Backup for a full-site archive, or copy the working directory plus a dump of your external database. See Section 15.

Q: How do I upgrade Halo? Pull the new image tag (e.g. halohub/halo:2.24 → a newer patch) and recreate the container with the same volume, or replace the JAR. Back up first. Database schema migrations run automatically on startup.

Q: Can I change the port? Yes. Set --server.port=... (and adjust your -p Docker mapping accordingly).

Q: How do I migrate from Halo 1.x or another CMS? Use a migration plugin under Tools. Note that attachment paths from 1.x are served via the built-in /upload/** resource mapping for compatibility.

Q: Can multiple people write on the same site? Yes. Create users, assign limited roles, and have contributors work from the User Center (/uc) so they never need full admin access.

Q: How do I enable social login (Google, GitHub, etc.)? Install an OAuth2 authentication plugin, then enable and configure it under System → Auth Providers.

Q: Is there an API? Yes — Halo exposes a comprehensive REST API (documented via OpenAPI) and an official JavaScript client. See the Admin Guide for the API surface and authentication.

Q: My site is reachable but links use the wrong domain. Set halo.external-url to your real public URL and restart.

Q: How do I get more themes and plugins? Browse the official application market at halo.run/store/apps and the community awesome-halo list.

19. Quick Reference

Default ports and paths

Essential startup settings

Console map

Useful Docker commands

# View logs
docker logs -f halo

# Stop / start / restart
docker stop halo && docker start halo
docker restart halo

# Upgrade (back up first!): pull a new tag and recreate with the SAME volume
docker pull halohub/halo:2.24
docker rm -f halo
docker run -d --name halo -p 8090:8090 -v ~/.halo2:/root/.halo2 halohub/halo:2.24

Note

For configuration internals, architecture, security hardening, performance tuning, the REST API surface, and theme/plugin development, continue to the Halo Admin Guide.