Deploying Halo

Introduction

Halo is a powerful, modern open-source blog and content management system built with Java and Spring Boot. Designed for developers and content creators, Halo offers a clean, intuitive interface with extensive customization options through themes and plugins. The platform supports Markdown editing, media management, and provides a RESTful API for headless CMS usage.

Originally developed for the Chinese market, Halo has grown into an international project with multi-language support and a vibrant ecosystem of themes and extensions. The application uses an embedded H2 database by default but supports PostgreSQL and MySQL for production deployments.

Key highlights of Halo:

Modern Architecture: Built with Spring Boot 3 and Vue.js for performance and maintainability
Plugin System: Extend functionality with a rich ecosystem of plugins
Theme Engine: Customize appearance with installable themes or create your own
Markdown Editor: Write content with a powerful Markdown editor and live preview
Media Management: Upload and organize images, videos, and files
SEO Friendly: Built-in SEO optimization with customizable meta tags
API-First: RESTful API enables headless CMS usage
Multi-Language: Support for multiple languages including English and Chinese

This guide walks through deploying Halo on Klutch.sh using Docker, configuring the database, and setting up the application for production blogging.

Prerequisites

Before deploying Halo on Klutch.sh, ensure you have:

A Klutch.sh account
A GitHub account with a repository for your Halo configuration
Basic familiarity with Docker and containerization concepts
(Optional) PostgreSQL or MySQL database for production use
(Optional) A custom domain for your blog

Preparing Your Repository

Create a GitHub repository with the following structure:

halo-deploy/
├── Dockerfile
├── .dockerignore
└── README.md

Creating the Dockerfile

Create a Dockerfile using the official Halo image:

FROM halohub/halo:2.20

# Environment variables for configuration
ENV HALO_WORK_DIR=/root/.halo2
ENV HALO_EXTERNAL_URL=${HALO_EXTERNAL_URL}

# Create working directory
RUN mkdir -p ${HALO_WORK_DIR}

# Expose the application port
EXPOSE 8090

# Default command with configuration
CMD ["java", "-jar", "/application/halo.jar", \
     "--halo.external-url=${HALO_EXTERNAL_URL}", \
     "--halo.security.initializer.superadminusername=${HALO_ADMIN_USERNAME}", \
     "--halo.security.initializer.superadminpassword=${HALO_ADMIN_PASSWORD}"]

Advanced Dockerfile with MySQL

For production deployments with MySQL:

FROM halohub/halo:2.20

ENV HALO_WORK_DIR=/root/.halo2
ENV SPRING_SQL_INIT_PLATFORM=mysql

EXPOSE 8090

CMD ["java", "-jar", "/application/halo.jar", \
     "--spring.r2dbc.url=${SPRING_R2DBC_URL}", \
     "--spring.r2dbc.username=${SPRING_R2DBC_USERNAME}", \
     "--spring.r2dbc.password=${SPRING_R2DBC_PASSWORD}", \
     "--spring.sql.init.platform=mysql", \
     "--halo.external-url=${HALO_EXTERNAL_URL}", \
     "--halo.security.initializer.superadminusername=${HALO_ADMIN_USERNAME}", \
     "--halo.security.initializer.superadminpassword=${HALO_ADMIN_PASSWORD}"]

Environment Variables Reference

Variable	Required	Description
`HALO_EXTERNAL_URL`	Yes	Public URL of your Halo instance
`HALO_ADMIN_USERNAME`	Yes	Initial admin username
`HALO_ADMIN_PASSWORD`	Yes	Initial admin password
`SPRING_R2DBC_URL`	No	Database connection URL (for MySQL/PostgreSQL)
`SPRING_R2DBC_USERNAME`	No	Database username
`SPRING_R2DBC_PASSWORD`	No	Database password
`SPRING_SQL_INIT_PLATFORM`	No	Database type (`mysql`, `postgresql`, or `h2`)

Deploying Halo on Klutch.sh

Push Your Repository to GitHub

git init
git add Dockerfile .dockerignore README.md
git commit -m "Initial Halo deployment configuration"
git remote add origin https://github.com/yourusername/halo-deploy.git
git push -u origin main

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project named “halo-blog” or similar.

Create a New App

Within your project, create a new app. Connect your GitHub account and select your Halo repository.

Configure HTTP Traffic

Select HTTP as the traffic type
Set the internal port to 8090

Set Environment Variables

Configure the following environment variables:

Variable	Value
`HALO_EXTERNAL_URL`	`https://your-app-name.klutch.sh`
`HALO_ADMIN_USERNAME`	Your desired admin username
`HALO_ADMIN_PASSWORD`	A secure admin password

Attach Persistent Volumes

Mount Path	Recommended Size	Purpose
`/root/.halo2`	10 GB	Database, themes, plugins, and uploads

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will build the container, attach volumes, and start Halo with HTTPS enabled.

Access Halo

Once deployment completes, access your Halo blog at https://your-app-name.klutch.sh. The admin console is available at https://your-app-name.klutch.sh/console.

Post-Deployment Configuration

Installing Themes

Access the admin console at /console
Navigate to Themes in the sidebar
Click Install to upload a theme file or install from URL
Activate your preferred theme

Installing Plugins

Navigate to Plugins in the admin console
Browse available plugins or upload custom ones
Enable plugins and configure their settings

Creating Your First Post

Navigate to Posts in the admin console
Click New Post
Write your content using the Markdown editor
Configure SEO settings and publish

Troubleshooting

Application Won’t Start

Verify all required environment variables are set
Check that port 8090 is configured correctly
Review application logs for startup errors

Database Issues

Ensure the persistent volume is mounted at /root/.halo2
For external databases, verify connection credentials
Check database connectivity from the container

Theme or Plugin Errors

Verify theme/plugin compatibility with your Halo version
Check console logs for JavaScript errors
Try disabling plugins to isolate issues

Additional Resources

Conclusion

Deploying Halo on Klutch.sh provides a modern, feature-rich blogging platform with automatic builds, persistent storage, and secure HTTPS access. The combination of Halo’s powerful plugin system, theme engine, and intuitive editor makes it an excellent choice for developers and content creators seeking a self-hosted blogging solution with full control over their content and data.