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:

  • Redirect 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”.

App Domain
Hyvor Blogs is designed to handle multiple domains in a single installation (custom domains for individual blogs). App Domain is where the main API and Console are hosted. All other domains are considered custom domains.

DNS Routing

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

Type
Host
Value
A
blogs.example.com
123.123.123.123

See Reverse Proxy if you are running Hyvor Blogs behind a reverse proxy.

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:

  • APP_SECRET: A strong random string. You can generate one using the following command: 
    openssl rand -base64 32
  • POSTGRES_PASSWORD: Use a strong, URL-safe password for the Postgres database. You can generate one using the following command: 
    openssl rand -base64 32 | tr '+/' '-_' | tr -d '='
  • DOMAIN_APP: The main domain where your Hyvor Blogs instance is hosted (e.g., blogs.example.com). This is where you access the Console, Sudo, and APIs.
  • OIDC_ISSUER_URL, OIDC_CLIENT_ID, OIDC_CLIENT_SECRET: Set these variables based on your OIDC provider configuration.

See Environment Variables for all available environment variables.

TLS Mode

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.

If you are running Hyvor Blogs behind a reverse proxy, see Reverse Proxy.

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 blogs

To verify your config:

docker compose exec blogs bin/console app:verify

Upgrading

To upgrade to the latest version, replace the image version in compose.yaml:

services:
  blogs:
    image: hyvor/blogs:<version>

Then, run:

docker compose up -d

Migrations will be applied automatically on startup.

Hyvor Blogs Logo