Halo

Halo is a self‑hosted, low‑code website builder that blends the simplicity of a visual editor with the extensibility expected by modern developers. Built on a micro‑service architecture, it exposes a unified RESTful API surface for content, users, and plugins while keeping the core lightweight enough to run inside a single Docker container. The system is designed for rapid iteration: developers can spin up a demo in minutes with docker run, then scale the database or storage backend as traffic grows.

Technical Stack & Architecture

• Core runtime: Java 17 + Spring Boot 3, leveraging Spring Cloud for service discovery and configuration. The core is packaged as a single JAR that runs inside the Docker image.
• Persistence: PostgreSQL (recommended) or MySQL for relational data; the schema is auto‑generated by JPA/Hibernate. File attachments are stored in an Attachment table with a flexible storage strategy that can be swapped for S3, MinIO, or local filesystem via plugin hooks.
• Search: Embedded Elasticsearch 8 for full‑text indexing; the index lifecycle is managed by a dedicated Spring bean that listens to content events.
• Plugin runtime: Uses Java’s ServiceLoader mechanism; plugins are Spring Boot starters that can be dropped into the plugins directory. The host scans this directory at startup and injects beans via classpath isolation, allowing runtime hot‑reload of plugins without restarting the core.
• Frontend: Vue 3 + Vite for the admin console; the public site is rendered by a pluggable theme engine that interprets JSON‑based page models. Themes are distributed as separate npm packages, enabling developers to ship new layouts or UI components without touching the core.

Core Capabilities

• Content API: CRUD operations for posts, pages, custom models, and taxonomy. Each model automatically generates a REST endpoint (/api/v1/{model}) with pagination, filtering, and search support.
• User & Auth: OAuth2 / OpenID Connect integration, LDAP sync, and role‑based access control. The authentication layer is pluggable, so developers can add SSO providers or MFA extensions.
• Attachment & Media: Unified media library with support for multiple storage backends. The API exposes POST /api/v1/attachments and streaming download URLs.
• Webhooks & Events: An event bus (ApplicationEventPublisher) allows plugins or external services to subscribe to content changes, user logins, or scheduled jobs. Webhook endpoints can be registered via the admin UI and consumed by CI/CD pipelines.
• Internationalization: The CMS stores locale strings in a key‑value table; plugins can register new locales, and the admin console provides a translation editor.

Deployment & Infrastructure

Halo ships as a single Docker image (halohub/halo:latest), making it trivial to deploy on any platform that supports Docker Compose, Kubernetes, or serverless containers. The recommended deployment pattern is:

1. Database: A dedicated PostgreSQL instance (or MySQL) with WAL‑based replication for high availability.
2. Storage: Persist the ~/.halo2 directory to a shared volume; swap to an object store via plugin if needed.
3. Reverse Proxy: Use Nginx or Traefik to terminate TLS and route /console vs. the public site.
4. Scaling: Since the core is stateless, multiple replicas can be spun up behind a load balancer. The only stateful component is the database and attachment storage, both of which can be clustered independently.

Integration & Extensibility

Halo’s plugin API is deliberately minimal yet powerful. Developers can:

• Add new data models by defining a JPA entity and exposing it through the @RestController stereotype; the framework auto‑generates CRUD endpoints.
• Inject custom authentication flows by implementing AuthenticationProvider and registering it in the Spring context.
• Extend the editor with new toolbar buttons via a JSON schema that the Vue editor consumes; plugins can bundle additional Markdown or HTML extensions.
• Hook into scheduled tasks using Spring’s @Scheduled annotation; the core exposes a job scheduler that persists cron expressions in the database.
• Expose external APIs: The built‑in API gateway can forward requests to third‑party services, or developers can expose their own endpoints that are discoverable by the CMS.

Developer Experience

• Configuration: All settings live in application.yml; the admin console exposes a form‑based editor that writes directly to this file, so developers can modify themes or storage settings without editing YAML.
• Documentation: The official docs (docs.halo.run) include a comprehensive API reference, plugin development guide, and migration scripts. The community forum (bbs.halo.run) is active, with a dedicated channel for plugin authors.
• Testing: The codebase has high test coverage (Codecov > 80%) and uses JUnit5 + Mockito for unit tests. Integration tests spin up an in‑memory PostgreSQL instance and mock external services, making CI pipelines straightforward.
• Community & Licensing: Released under Apache 2.0, Halo benefits from a growing ecosystem of plugins (100+ on the store) and a contributor base that actively maintains the repository. The open‑source nature ensures no vendor lock‑in, and the modular architecture lets teams ship custom features without waiting for upstream releases.

Use Cases

• Personal & Portfolio Sites: Quick bootstrap of a content‑rich site with custom themes