The editor

Running it for a team

Run the editor on a server so everyone can reach it, safely: its own address, TLS, previews on a separate domain, and the same secret on every copy.

This page is for whoever looks after the server. It assumes you've run the editor on your own computer once (Run the editor) and know your way around a Linux server and a web server like nginx or Caddy.

Where it runs

  • Never on the server that hosts your public site. The editor holds people's sign-ins; your public site should be nothing but files. A separate small server, or a container, is right.
  • It needs git installed, and room for a copy of each site people open.

editor.yaml for a server

listen: 127.0.0.1:8190                 # the editor, behind your web server
public_url: https://edit.example.org   # how browsers reach it; sign-in returns here
cache: /var/cache/hotdog-cms/editor     # people's copies of sites

forges:
  - host: github.com
    kind: github
    client_id: Ov23liABCDEF12345678
    client_secret_env: HOTDOG_GITHUB_SECRET
    discover: { owners: [your-org] }    # only your organization's sites

sites:
  - name: Bakery on Main
    repo: https://github.com/your-org/bakery-site.git
    branch: main
    preview: { domain: preview.example-previews.net }   # where branch previews are served

live:                                  # the live preview of pages being edited
  listen: 127.0.0.1:8191
  domain: live.example-previews.net    # previews are <code>.live.example-previews.net

links:                                 # yours, in the editor's footer
  - { name: Help, url: https://example.org/help/ }

The sign-in app's redirect URL becomes https://edit.example.org/auth/callback.

Two addresses, two domains

The editor listens on two addresses: the editor itself, and the live preview of pages being edited. Previews run your site's own pages, scripts included, so they're kept away from the editor:

  • Put the live preview (and branch previews) on a different registered domain from the editor, such as edit.example.org for the editor and example-previews.net for previews. A different domain is a much stronger wall than a subdomain.
  • The live preview needs a wildcard name: point *.live.example-previews.net at the server, with a wildcard TLS certificate.

TLS and the web server

Put both behind your web server with TLS (https). In nginx:

server {
    listen 443 ssl;
    server_name edit.example.org;
    location / {
        proxy_pass http://127.0.0.1:8190;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto https;
    }
}
server {
    listen 443 ssl;
    server_name *.live.example-previews.net;
    location / {
        proxy_pass http://127.0.0.1:8191;
        proxy_set_header Host $host;
    }
}

Secrets

Set them in the service's environment, never in editor.yaml:

  • HOTDOG_EDITOR_SECRET: at least 32 characters (openssl rand -hex 32). Every copy of the editor serving the same people needs the same one, and changing it signs everyone out.
  • The client secret for each platform, under the names client_secret_env gives.

As a service

A systemd unit, for example:

[Unit]
Description=HotDog CMS editor
After=network-online.target
Wants=network-online.target

[Service]
User=hotdog-editor
EnvironmentFile=/etc/hotdog-cms/editor.env
ExecStart=/usr/local/bin/hotdog-cms editor -config /etc/hotdog-cms/editor.yaml
Restart=on-failure
NoNewPrivileges=yes
ProtectSystem=strict
ReadWritePaths=/var/cache/hotdog-cms

[Install]
WantedBy=multi-user.target

with the secrets in /etc/hotdog-cms/editor.env, readable only by root and the service:

HOTDOG_EDITOR_SECRET=…
HOTDOG_GITHUB_SECRET=…

Who can do what

The editor stores no permissions. Everything comes from your git platform:

  • Read a site: they can look, but not save.
  • Write: they can make drafts and open reviews.
  • Maintain: they can also change publish targets and pipeline files.

Who may publish (merge) is the platform's decision, branch protection included. To stop people publishing their own changes unreviewed, require an approval on the publishing branch, in your platform's branch protection settings. Two-factor sign-in and passkeys work as the platform asks.

The editor's footer links to its source code, as its license (AGPL) asks of software people use over a network. As released, it points at the exact version you're running. If you change HotDog's code, publish your changes and set source: in editor.yaml to where they are.