Halo Admin Guide

This guide is the operational and architectural reference for Halo, the open-source website-building platform. It is written for administrators, DevOps engineers, and developers who deploy, operate, secure, extend, or contribute to Halo. It covers the system architecture, the complete configuration surface, deployment patterns, security hardening, day-to-day operations, the REST API, and the internals needed to build themes and plugins or to reason about the codebase.

Note

Halo is a single Spring Boot application written in Java 21 using the reactive (WebFlux) stack, fronted by a Vue 3 + TypeScript single-page console. It uses a Kubernetes-style extension/custom-resource model for all of its data. Understanding that model (Section 3) is the key to understanding everything else.

1. Executive Summary

Halo is designed so that a single operator can run a production website with minimal moving parts: one application process, one database, and a single working directory that holds all mutable state. Horizontal complexity (themes, plugins, storage backends, auth providers) is added at runtime through the extension and plugin systems rather than by changing core code.

2. System Architecture

2.1 High-level component diagram

                          ┌──────────────────────────────────────────────┐
   Browser (visitors)     │                   Halo JVM                    │
        │                 │            (Spring Boot 3 / WebFlux)          │
        ▼                 │                                               │
  ┌───────────┐  HTTP     │  ┌────────────────────────────────────────┐  │
  │  Reverse  │──────────▶│  │ Netty reactive web server  :8090       │  │
  │   proxy   │  :8090    │  └───────────────┬────────────────────────┘  │
  │ (nginx/   │           │                  │  Spring Security filter    │
  │  caddy/   │◀──────────│                  │  chain (reactive)          │
  │  1Panel)  │           │     ┌────────────┼────────────┬───────────┐  │
  └───────────┘           │     ▼            ▼            ▼           ▼  │
        ▲                 │  Theme       /apis REST    /console     /uc  │
        │                 │  router      endpoints     (SPA)       (SPA) │
  Browser (admins)        │  (Thymeleaf) (console/uc/   static      static│
                          │              public/ext)   assets      assets│
                          │     │            │                           │
                          │     ▼            ▼                           │
                          │  ┌──────────────────────────────────────┐   │
                          │  │  Extension (custom-resource) layer    │   │
                          │  │  Scheme · ReactiveExtensionClient ·   │   │
                          │  │  Reconcilers (controllers) · Watchers │   │
                          │  │  · Lucene indexers                    │   │
                          │  └───────┬───────────────────┬──────────┘   │
                          │          ▼                   ▼               │
                          │   ┌────────────┐      ┌─────────────┐        │
                          │   │ R2DBC repo │      │  PF4J plugin │        │
                          │   │  (DB store)│      │   manager    │        │
                          │   └─────┬──────┘      └──────┬──────┘        │
                          └─────────┼────────────────────┼───────────────┘
                                    ▼                     ▼
                          ┌──────────────────┐   ┌──────────────────┐
                          │  Database         │   │ Working directory │
                          │ H2/PG/MySQL/Maria │   │  ~/.halo2         │
                          └──────────────────┘   │  db/ attachments/ │
                                                  │  themes/ plugins/ │
                                                  │  logs/ backups/   │
                                                  └──────────────────┘

2.2 Runtime stack

Note

The application runs on virtual threads (Project Loom) and a reactive web stack. Blocking calls inside reactive pipelines are an anti-pattern here; plugin authors must respect the reactive contract (return Mono/Flux, never block the event loop).

2.3 Gradle multi-module layout

Halo is a Gradle multi-project build. The modules:

The front-end :ui module is itself a pnpm workspace with published packages:

Tip

The console (console.html) and User Center (uc.html) are two entry points of one Vite multi-page app sharing ui/src. In production the backend serves /console/** → console.html, /uc/** → uc.html, and /ui-assets/** → static assets.

3. The Extension (Custom-Resource) Model — Architectural Keystone

Everything Halo stores — posts, pages, users, roles, themes, plugins, comments, settings — is an Extension: a typed, versioned, JSON document modeled directly on Kubernetes custom resources. Internalizing this model is the single most important thing for operating or extending Halo.

3.1 Core concepts

3.2 How a request flows

1. A console/API call hits a reactive endpoint (for example "create post").
2. The handler builds a Post extension and persists it via ReactiveExtensionClient.create(...).
3. The extension is serialized to JSON and stored as a row in the database (R2DBC).
4. A watcher notices the new/changed extension and notifies the registered reconciler (controller).
5. The reconciler performs side effects: generating permalinks, updating counters, reindexing for search, rendering, cleanup, etc. — and may update the extension's status.
6. Indexers maintain in-memory indexes (backed by Lucene for full-text) so list/query operations (ListOptions, field/label selectors) are fast without scanning the database.

Important

Optimistic concurrency is enforced via metadata.version. Updates carry the version they were read at; a mismatch means another writer won, and the update is rejected so the caller can retry. Plugin code must handle these retries.

3.3 Why this matters operationally

• The database is a document store of JSON extensions, not a hand-designed relational schema you query directly. Do not edit rows by hand.
• Backups must capture extensions + working files together — which is exactly what the full-site backup feature does (Section 9).
• Reconcilers run asynchronously. After an import or restore, give controllers time to converge (rebuild indexes, regenerate derived data).
• Plugins extend the model by registering new schemes and reconcilers — they participate as first-class citizens in the same machinery as core types.

4. Configuration Mastery

Halo is configured the standard Spring Boot way. Every setting can be supplied as:

1. A command-line argument: --halo.external-url=https://example.com/
2. An environment variable: HALO_EXTERNAL_URL=https://example.com/ (relaxed binding: dots/dashes → underscores, uppercased)
3. A key in application.yaml placed in the working directory or on the classpath.

Precedence (highest first): command-line args → environment variables → external application.yaml → bundled defaults. In the official Docker image, SPRING_CONFIG_LOCATION is set to optional:classpath:/;optional:file:/root/.halo2/, so a application.yaml you drop into the mounted working directory is automatically picked up.

4.1 halo.* — application settings

These are bound from run.halo.app.infra.properties.HaloProperties and its nested classes (@ConfigurationProperties(prefix = "halo")). This is the authoritative, source-derived reference.

Top-level halo

halo.security.*

Note

JWT/OAuth2 signing keys are bound separately (JwtProperties) under halo.security.oauth2.jwt.*: public-key-location, private-key-location, issuer-uri, and jws-algorithm (default RS256). Halo manages RSA keys in the working directory by default; only override these if you have a specific key-management strategy.

halo.attachment.*

halo.theme.*, halo.ui.*, halo.extension.*

halo.notification.*

4.2 spring.* and server settings (from application.yaml)

4.3 Rate limiters (resilience4j.ratelimiter.configs.*)

Halo ships these named limiters (defaults from application.yaml). They protect abuse-prone flows.

4.4 Environment variables and JVM options

Tip

Any application-<profile>.yaml (e.g. application-postgresql.yaml) ships in the image as a convenience profile. Activate with --spring.profiles.active=postgresql, or just set the three spring.r2dbc.* / spring.sql.init.platform values directly as shown in the User Guide.

5. Database

5.1 Supported engines and selection

Halo uses R2DBC (reactive) drivers, not JDBC. The bundled runtime drivers are r2dbc-h2, r2dbc-postgresql (+ postgresql), r2dbc-mariadb, and r2dbc-mysql (io.asyncer:r2dbc-mysql).

Important

spring.sql.init.platform must match your engine. It selects both the schema initialization SQL and the migration script directory (classpath:/db/migration/<platform>/*.sql). A mismatch causes startup failures or wrong-dialect SQL.

5.2 Schema and migrations

• Initial schemas ship as schema-h2.sql, schema-mysql.sql, schema-mariadb.sql, schema-postgresql.sql.
• Ongoing migrations live in db/migration/{h2,mysql,mariadb,postgresql}/ and are applied by r2dbc-migrate at startup.
• spring.sql.init.mode: always means initialization runs on every boot (idempotent).

Because all domain data is stored as JSON extensions (Section 3), the relational schema is intentionally generic (a small set of tables holding serialized extensions plus supporting structures). Do not hand-edit rows. Use the API or the console.

5.3 Connection pooling

Prefix the R2DBC URL with r2dbc:pool: to enable connection pooling for external databases (as in the Compose example). Tune pool size via standard Spring R2DBC pool properties if needed.

6. Deployment

6.1 Docker image internals

The image is built from eclipse-temurin:21-jre using Spring Boot's layered jar + tools extraction, and it pre-computes a CDS archive for faster startup:

• java -Djarmode=tools -jar application.jar extract --layers splits the jar into dependencies/, spring-boot-loader/, snapshot-dependencies/, application/ layers (better Docker layer caching).
• A build step runs -XX:ArchiveClassesAtExit=application.jsa -Dspring.context.exit=onRefresh to generate an AppCDS archive, then the entrypoint launches with -XX:SharedArchiveFile=application.jsa for reduced startup time and memory.
• EXPOSE 8090; entrypoint execs java ${JVM_OPTS} ... -jar application.jar "$@", so extra --flag=value args you pass to docker run reach the app.

Official image coordinates:

Tip

Set JVM_OPTS to bound heap in containers, e.g. -e JVM_OPTS="-Xmx512m -Xms512m". The Compose example uses 256m; size it to your traffic and plugin set.

6.2 Reverse proxy

Run Halo behind a proxy that terminates TLS and forwards all paths (/, /console, /uc, /apis/**, /ui-assets/**). Because server.forward-headers-strategy: native, Halo trusts X-Forwarded-Proto/X-Forwarded-Host/X-Forwarded-For to reconstruct correct external URLs.

Minimal Nginx location:

location / {
    proxy_pass http://127.0.0.1:8090;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_http_version 1.1;
}

Note

The project recommends 1Panel (a server management panel) for turnkey deployment, which wires up the reverse proxy, SSL certificates, and backup/upgrade tasks automatically.

6.3 Building from source

# Full build (backend + frontend) — produces application/build/libs/halo-*.jar
./gradlew clean build

# Skip checks for a faster local build
./gradlew clean build -x check

# Build the Docker image to local Docker
./gradlew :application:bootBuildImage

The build flow: :ui:doBuild (pnpm builds Vue → ui/build/dist) → copyUiDist copies it into the application's resources → bootJar packages the executable JAR → createChecksums writes SHA-256 sidecars. Several first-party plugins (comment-widget, search-widget, sitemap, feed, shiki, editor-hyperlink-card, app-store) are downloaded into resources/main/presets/plugins by the downloadPluginPresets task so a fresh install has working defaults.

Note

Requirements to build from source: JDK 21, Node ^24, and pnpm 10.x (the repo pins packageManager). The Gradle Node plugin provisions Node automatically for CI builds.

7. Security

7.1 Authentication mechanisms

Halo's reactive Spring Security chain (run.halo.app.security.authentication.*) supports multiple credential types:

JWTs are signed with RSA keys (RS256 by default) managed under the working directory; OAuth2 jose handles validation.

7.2 Authorization (RBAC)

Authorization (security/authorization) is role-based. Roles are extensions that bundle permission rules; users are granted roles; effective permissions are the union. UI routes also carry permissions metadata so the console hides actions a user cannot perform. The super-role has unrestricted access (including sensitive actuator data — see below).

7.3 Transport and header hardening

Defaults set sane security headers: X-Frame-Options: SAMEORIGIN, Referrer-Policy: strict-origin-when-cross-origin, configurable CORS, and HTTPS-awareness via forwarded headers. Run behind TLS in production.

7.4 Abuse protection

Resilience4j rate limiters (Section 4.3) throttle login, signup, comment creation, and email/password-reset flows. These materially reduce credential-stuffing and spam without extra infrastructure.

7.5 Hardening checklist and honest risk notes

• [ ] Change default database credentials. The bundled application.yaml ships admin/123456 for the file H2 database. For any external database, set strong spring.r2dbc.username/password. Never expose the H2 file DB beyond the host.
• [ ] Restrict Actuator exposure. application.yaml sets management.endpoints.web.exposure.include: "*" and marks shutdown and heapdump access as unrestricted. These are powerful: shutdown can stop the app and heapdump can leak memory contents. They run on the same port (8090). Do not expose /actuator/** to the public — block it at the reverse proxy, or override the exposure to a minimal set (health,info) and lock down shutdown/heapdump in production. Health details are already gated (show-details: when-authorized, roles: super-role).
• [ ] Set halo.external-url to your real HTTPS URL so links and OAuth redirects are correct.
• [ ] Enable 2FA for administrator accounts (halo.security.two-factor-auth.disabled=false, then enroll per user in /uc).
• [ ] Scope and rotate PATs; treat them as secrets.
• [ ] Vet plugins/themes. Plugins run in-process with broad access; only install trusted packages.
• [ ] Keep Halo updated — schema migrations run automatically; security fixes land in patch releases.
• [ ] Run as non-root where possible and mount the working directory on durable, backed-up storage.

Caution

The combination of exposure.include: "*" + unrestricted shutdown/heapdump is convenient in development but is the single most important thing to lock down before exposing Halo to the internet.

8. The REST API

Halo is API-first: the entire console and User Center are built on the same public REST API, documented via OpenAPI (springdoc) and consumed through the generated @halo-dev/api-client.

8.1 API groups

The OpenAPI spec is generated into five grouped documents (from the build's openApi.groupedApiMappings):

Endpoints live under /apis/... paths, versioned v1alpha1, grouped by API group (e.g. content.halo.run, api.console.halo.run, uc.api.halo.run). Example: GET /apis/api.console.halo.run/v1alpha1/posts.

8.2 Authentication

Authenticate API calls with either a session (cookie, as the SPA does) or a personal access token as a bearer token:

curl -H "Authorization: Bearer <your-PAT>" \
  https://blog.example.com/apis/api.console.halo.run/v1alpha1/posts

8.3 JavaScript client

The official client wraps every group:

import {
  coreApiClient,     // CRUD over custom models (extensions)
  consoleApiClient,  // console operations
  ucApiClient,       // user-center operations
  publicApiClient,   // public endpoints
  createCoreApiClient,
} from "@halo-dev/api-client";

coreApiClient.content.post.listPost().then((res) => {
  console.log(res.data.items);
});

// External app: bring your own axios instance
import axios from "axios";
const core = createCoreApiClient(axios.create({ baseURL: "http://localhost:8090" }));

Note

The client is OpenAPI-generated (openapi-generator typescript-axios) from api-docs/openapi/v3_0/aggregated.json. Regenerate it with the api-client:gen pnpm script whenever the backend API changes. The OpenAPI doc itself is produced by running the app under the doc profile (--spring.profiles.active=doc) and scraping /v3/api-docs/....

9. Operations

9.1 Working-directory layout

Everything mutable lives under halo.work-dir (~/.halo2):

Important

The working directory is the site. Mount it on durable storage, monitor its disk usage (attachments and logs grow), and include it in your backup strategy.

9.2 Start / stop / logs

# Docker
docker logs -f halo
docker restart halo
docker stop halo && docker start halo

# JAR (systemd recommended in production)
java -jar halo.jar --halo.work-dir=/opt/halo/data
tail -f /opt/halo/data/logs/halo.log

9.3 Health and monitoring

Spring Boot Actuator is enabled with Kubernetes-style probes:

Example Kubernetes probes:

livenessProbe:
  httpGet: { path: /actuator/health/liveness, port: 8090 }
readinessProbe:
  httpGet: { path: /actuator/health/readiness, port: 8090 }

Warning

Restrict /actuator/** at the proxy (see Section 7.5). Probes can be allowed internally while the rest of the actuator surface is blocked from the public internet.

9.4 Backup and restore

The full-site backup (migration.halo.run/v1alpha1, Kind=Backup) bundles database extensions + working-directory files into a single ZIP under ${work-dir}/backups/. Operate it from System → Backup in the console:

• Backups run asynchronously; the Backup resource's status.phase moves Pending → Running → Succeeded/Failed, with status.filename on success.
• spec.autoDeleteWhen controls retention; users can grant backup permission to specific accounts.
• Backup is the supported cross-database migration path (H2 → PostgreSQL, etc.).

Important

Take a fresh backup before restoring or upgrading. Restored data may have creationTimestamp overwritten by the current time. Supported for Halo 2.8.x and newer.

9.5 Upgrades

1. Back up (console backup + DB dump if external).
2. Pull the new image tag / replace the JAR.
3. Recreate the container with the same working-directory volume and same database.
4. On startup, r2dbc-migrate applies any new schema migrations automatically.
5. Verify the console loads and reconcilers have converged (search index, counters).

10. Performance Tuning

Tip

Halo scales vertically very well on a single node thanks to the reactive stack + virtual threads. The usual bottlenecks are the database and image processing, not the web tier.

11. Extending Halo

11.1 Plugins (PF4J)

Plugins are JARs loaded by PF4J with isolated classloaders. A plugin can:

• Register new extension schemes and reconcilers (new custom resources + controllers).
• Add REST endpoints (@ApiVersion-style routes under /apis/...).
• Contribute extension points and implementations (e.g. storage policies, auth providers, attachment handlers, notifier types).
• Ship a front-end (console/UC assets) built with @halo-dev/ui-plugin-bundler-kit, registered via definePlugin (routes, menu entries, components, extensionPoints).
• Declare settings (a setting.yaml form) and persist values as a ConfigMap extension.

Plugin lifecycle: install → enable → (configure) → disable → uninstall, all from System → Plugins or the API. Plugins depend on the :platform:plugin BOM and the :api module so they compile against the host's exact library versions.

Note

Build plugin front-ends with Rsbuild for large/code-split UIs and Vite for simpler ones (@halo-dev/ui-plugin-bundler-kit supports both). Exclude @halo-dev/api-client and axios from the bundle — the host provides them.

11.2 Themes (Thymeleaf)

Themes render the public site with Thymeleaf reactive templates. The theme system provides:

• Router factories (theme/router/factories) that build dynamic routes for posts, pages, categories, tags, archives, and custom patterns based on permalink settings.
• Finders (theme/finders) — a safe, read-only data API (posts, categories, comments, menus, site stats) that templates call to fetch content.
• Template resolution that supports per-post/page/category template overrides.
• A theme settings form (rendered from the theme's definition) and theme-scoped configuration stored as extensions.

A theme package is a .zip containing templates, static assets, and a manifest. The default bundled theme is "earth" (classpath:themes/theme-earth.zip).

Tip

The front-end @halo-dev/components (UI), @halo-dev/ui-shared (plugin SDK), and @halo-dev/richtext-editor packages are published to npm so plugin authors reuse the exact components and editor the core uses. Custom FormKit inputs (code, attachment, repeater, list, select, secret, postSelect, categorySelect, tagSelect, menu selectors, verificationForm, …) are available to plugin/theme setting forms.

11.3 Front-end module/route generation

Console routes and sidebar menus are generated dynamically from three sources: base routes (src/router/routes.config.ts), core module routes (src/modules/**/module.ts), and plugin routes — all declared via definePlugin. A route's meta.menu object (name, group, icon, priority, mobile) places it in the sidebar; meta.permissions gates visibility by RBAC permission. Core menu groups: dashboard, content, interface, system, tool.

12. Repository Structure (for contributors)

halo/
├── api/                      # Public plugin API (run.halo.app.*), published library
│   └── src/main/java/run/halo/app/{extension,security,core,plugin,theme,...}
├── application/              # Runnable Spring Boot app
│   └── src/main/
│       ├── java/run/halo/app/
│       │   ├── Application.java            # main()
│       │   ├── infra/properties/           # @ConfigurationProperties (halo.*)
│       │   ├── extension/                   # extension store, controllers, indexers
│       │   ├── security/                    # auth (oauth2, twofactor, rememberme, token, pat)
│       │   ├── core/                        # users, attachments, counters, endpoints
│       │   ├── content/                     # posts, pages, comments, permalinks
│       │   ├── theme/                       # router factories, finders, dialect, engine
│       │   ├── plugin/                      # PF4J integration, extension points
│       │   ├── notification/                # notifications + cleanup
│       │   ├── search/                      # Lucene full-text search
│       │   └── migration/                   # backup/restore
│       └── resources/
│           ├── application*.yaml            # config + per-DB profiles
│           ├── db/migration/{h2,mysql,mariadb,postgresql}/
│           ├── schema-*.sql
│           ├── themes/                       # default theme
│           └── config/                       # i18n, uap (ua-parser regexes)
├── platform/{application,plugin}/  # Gradle java-platform BOMs
├── buildSrc/                  # Groovy convention plugins (halo.publish)
├── ui/                        # Vue 3 + TS front-end (pnpm workspace)
│   ├── console-src/           # Console SPA
│   ├── uc-src/                # User Center SPA
│   ├── src/                   # shared (components, formkit, locales, router)
│   └── packages/              # api-client, components, ui-shared, editor, bundler-kit
├── api-docs/openapi/v3_0/     # generated OpenAPI specs
├── docs/                      # developer/extension-point design proposals
├── e2e/                       # api-testing based end-to-end suite
├── Dockerfile                 # layered + CDS image
└── settings.gradle / build.gradle / gradle.properties

Module reference (selected core packages)

13. Testing Strategy

Run the backend tests: ./gradlew test. Run the full check (lint + typecheck + unit) for the UI: pnpm --filter ... check (wired through Gradle :ui:check). E2E: cd e2e && ./start.sh.

Note

Add or update e2e cases when you add or change APIs — the e2e/README makes this a contribution expectation.

14. Troubleshooting (Operations)

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

halo.use-absolute-permalink=true without halo.external-url. Set the external URL or disable absolute permalinks. (Validated by HaloProperties.validate.)

Startup fails: External URL must be a http or https URL.

halo.external-url is not a valid HTTP/HTTPS URL (opaque or missing authority/scheme). Provide a full URL like https://blog.example.com/.

Startup fails: Public/Private key location does not exist

JWT signing keys missing at the configured halo.security.oauth2.jwt.*-key-location. Use the defaults (Halo manages keys under the work dir) or point to existing RSA key files.

App starts but database errors / wrong SQL dialect

spring.sql.init.platform does not match the engine in spring.r2dbc.url. Align them (postgresql/mysql/mariadb/h2).

/console 404 or assets missing behind a proxy

The proxy isn't forwarding all paths. Forward /, /console, /uc, /apis/**, /ui-assets/**. Confirm X-Forwarded-* headers are passed (forward-headers-strategy: native).

Data lost on container recreate

No persistent volume. Always mount -v <host>:/root/.halo2. The working directory holds the entire site.

Actuator endpoint reachable from the internet

exposure.include: "*". Block /actuator/** at the proxy and/or override exposure to health,info; lock down shutdown/heapdump.

High memory / OOM

Bound heap via JVM_OPTS; check Caffeine maximumSize, max-in-memory-size, thumbnail concurrency, and large attachment processing. Inspect logs/halo.log.

Slow search or stale lists after import/restore

Reconcilers/indexers are still converging. Allow time; check logs for indexing activity. A restart forces index rebuild.

15. Quick Reference

Key files

Default endpoints

Minimal production startup

docker run -d --name halo \
  -p 8090:8090 \
  -v /srv/halo:/root/.halo2 \
  -e TZ=UTC \
  -e JVM_OPTS="-Xmx512m -Xms512m" \
  halohub/halo:2.24 \
  --halo.external-url=https://blog.example.com/ \
  --spring.r2dbc.url=r2dbc:pool:postgresql://db:5432/halo \
  --spring.r2dbc.username=halo \
  --spring.r2dbc.password=CHANGE_ME \
  --spring.sql.init.platform=postgresql \
  --halo.security.two-factor-auth.disabled=false

Source / reference