Self-Hosting Overview

Overview

Self-hosting means running Herald under the MIT license on your own infrastructure. You bring the server, the database, the AI provider key, and the SMTP credentials; Herald handles everything else.

The self-hosted edition is the same code that powers the cloud version. Same UI, same GitHub integration, same widget, same email subscriber flow. The only differences are operational: on cloud, we manage infrastructure, AI provisioning, and email delivery; on self-hosted, you do.

When to self-host: compliance or data-residency requirements; you'd rather use your own AI provider account; you want to bring your own SMTP and email-from domain; or you'd rather pay for infrastructure than for a SaaS subscription.

When to use cloud: you'd rather not run anything yourself; you want the managed analytics dashboard (cloud-only); your team prefers paying a flat monthly subscription over operating infrastructure.

Requirements

To self-host Herald you need:

• A server capable of running a long-lived web service (a small VPS works; container-based deployment is supported)
• A database — the repository README documents supported databases and current versions
• An OpenAI or Anthropic API key for AI changelog drafts — Herald uses your key, you pay your provider directly
• SMTP credentials for outbound email — any provider with SMTP works (SES, Postmark, Mailgun, SendGrid, etc.)
• A domain or subdomain to serve the changelog and admin UI

The exact runtime version, dependency list, and recommended VM size live in the repository README so they stay in sync with each release.

What cloud manages for you

If you're on a cloud plan instead, Herald handles all of the above for you:

• Infrastructure — we host and operate the application
• AI provisioning — we provide and manage the AI provider account; you don't need your own OpenAI or Anthropic key
• Email delivery — managed sending on Solo; custom sender domain on Team and Studio
• Database, backups, upgrades — handled
• Managed analytics dashboard — subscriber growth, view counts, read rates; cloud-only

Same Herald codebase runs both editions. The only practical difference is what you're paying for: a server you operate, vs. a subscription where we operate it.

Installation

The canonical install steps live in the repository: github.com/ThinkOodle/herald. Steps move with releases, so we keep them at the source rather than duplicating them here.

At a high level, installing Herald involves:

1. Clone the repository or pull the published container image
2. Provision a database the application can reach
3. Set environment variables for database connection, AI provider API key, SMTP credentials, an application secret, and your hosting URL (see Configuration below for the categories — exact variable names are in the README)
4. Run the database migrations included in the release
5. Start the web service behind your reverse proxy of choice (Caddy, Nginx, Traefik — anything that terminates TLS works)
6. Visit your hosting URL and complete the first-run admin setup

Total setup time on a typical VPS with a managed database is under 30 minutes. If you hit anything that's not in the README, open an issue — we'd rather fix the docs than have you guess.

Configuration

Herald is configured via environment variables. The categories you'll need to set:

• Database connection — connection string for your database
• AI provider — your OpenAI or Anthropic API key, plus the model name to use for drafts (defaults work; can be swapped per-project later)
• SMTP credentials — host, port, username, password, and the from-address for outbound email
• Application secret — a long random string used to sign sessions and JWTs; set once at install and don't rotate without warning users
• Hosting URL — the public URL where Herald is reachable (used in widget embeds, email links, and OAuth callbacks)
• Optional: GitHub App credentials — if you want webhook-based PR sync in addition to polling, configure a GitHub App and set its credentials

The canonical environment variable names and the full reference live in the repository README and in the example .env file shipped with each release. We keep it at the source so it can't drift from the actual code.

Upgrading

Herald uses semantic versioning. Patch releases (1.2.3 → 1.2.4) are safe to apply directly. Minor releases (1.2 → 1.3) may include database migrations; review the release notes before applying. Major releases (1.x → 2.x) may include breaking config changes; plan the upgrade window accordingly.

Recommended upgrade flow:

1. Read the release notes for the version you're upgrading to (linked from the repository's Releases page)
2. Back up your database — always
3. Pull the new release (git pull, container repull, or whatever your deployment method uses)
4. Run the database migrations included in the release
5. Restart the web service
6. Confirm the admin UI loads and a recent published changelog still renders correctly

If you have a staging environment, do the upgrade there first. Most upgrades are uneventful, but the cost of a 30-minute staging dry-run is much lower than the cost of finding a migration issue against your production data.

Rollback: if something goes wrong, restoring the database backup from before the migration is the fastest path back. Down-migrations are not guaranteed; the canonical rollback is a database restore.