Deploy

Let’s deploy Hyvor Blogs on your server using Docker Compose. You can easily adapt this guide to other deployment methods such as Kubernetes.

Prerequisites

Server: A Linux server with at least 1 GB RAM and 1 vCPUs.

Docker: Install Docker following the official guide.

OpenID Connect (OIDC) Provider: Hyvor Blogs relies on OIDC for authentication. Create an application in your OIDC provider and obtain the issuer URL, client ID, and client secret. Then, allow the following URLs:

  • Callback URL: https://<your-app-domain>/api/oidc/callback
  • Logout URL: https://<your-app-domain>

Domain: Domain name for your Hyvor Blogs instance. This is called the “App Domain”.

DNS Routing

Point your app domain to your server’s IP address.

Type
Host
Value
A
blogs.example.com
123.123.123.123

Install

Download the latest release tarball from the releases page:

curl -L https://github.com/hyvor/blogs/releases/latest/download/deploy.tar.gz | tar -xz
cd deploy

This gives you two files:

deploy/
   compose.yaml
   .env

Configure

Edit the .env file and fill in the required values:

# Required
APP_SECRET=           # Run: openssl rand -base64 32
POSTGRES_PASSWORD=    # A strong password for the database
DOMAIN_APP=           # e.g. blogs.example.com
DELIVERY_URL=         # e.g. https://blogs.example.com
MERCURE_JWT_SECRET=   # Run: openssl rand -base64 32

# OIDC (on-prem authentication)
OIDC_ISSUER_URL=      # e.g. https://accounts.google.com
OIDC_CLIENT_ID=
OIDC_CLIENT_SECRET=

# S3-compatible storage
S3_ACCESS_KEY_ID=
S3_SECRET_ACCESS_KEY=
S3_ENDPOINT=          # e.g. https://s3.amazonaws.com
S3_BUCKET=
S3_USE_PATH_STYLE_ENDPOINT=false

The DATABASE_URL is pre-configured to connect to the Postgres service defined in compose.yaml using POSTGRES_PASSWORD, so you do not need to change it.

TLS Configuration

TLS_MODE controls how HTTPS is handled for the app domain (DOMAIN_APP). It does not affect custom domains attached to individual blogs, which always get TLS certificates automatically. Set it to one of the following:

Mode
Behavior
auto
Default. Caddy automatically obtains and renews a certificate from Let's Encrypt. Requires DOMAIN_APP to be publicly resolvable, with ports 80 and 443 reachable from the internet.
external
Use this if you run a reverse proxy (Nginx, Traefik, a load balancer, etc.) in front of Hyvor Blogs that terminates TLS. The container is reached over HTTP only; only port 80 needs to be published. The container does not redirect HTTP to HTTPS itself in this mode — handle that in your reverse proxy if needed. Make sure your proxy forwards the X-Forwarded-Proto: https and X-Forwarded-For headers, and that its IP is included in TRUSTED_PROXIES.
manual
Provide your own certificate and key by mounting them into the container at /certs/cert.pem and /certs/key.pem.
disabled
TLS is fully disabled and no HTTPS redirect happens. All links are generated as http://. Only use this on a trusted internal network.

Start

docker compose up -d

Hyvor Blogs will start and run database migrations automatically on the first launch.

To check logs:

docker compose logs -f

Upgrading

To upgrade to the latest version, pull the new image and restart the container:

docker compose pull
docker compose up -d

Migrations are applied automatically on startup.

Hyvor Blogs Logo