ContextQMD
Back to Ghost

Dev Gateway (Caddy)

docker/dev-gateway/README.md

6.57.05.0 KB
Original Source

Dev Gateway (Caddy)

This directory contains the Caddy reverse proxy configuration for the Ghost development environment.

Purpose

The Caddy reverse proxy container:

  1. Routes Ghost requests to the Ghost container backend
  2. Proxies asset requests to local dev servers running on the host
  3. Enables hot-reload for frontend development without rebuilding Ghost

Configuration

Environment Variables

Caddy uses environment variables (set in compose.dev.yaml) to configure proxy targets:

  • GHOST_BACKEND - Ghost container hostname (e.g., ghost-dev:2368)
  • ADMIN_DEV_SERVER - React admin dev server (e.g., host.docker.internal:5174)
  • ADMIN_LIVE_RELOAD_SERVER - Ember live reload WebSocket (e.g., host.docker.internal:4200)
  • PORTAL_DEV_SERVER - Portal dev server (e.g., host.docker.internal:4175)
  • COMMENTS_DEV_SERVER - Comments UI (e.g., host.docker.internal:7173)
  • SIGNUP_DEV_SERVER - Signup form (e.g., host.docker.internal:6174)
  • SEARCH_DEV_SERVER - Sodo search (e.g., host.docker.internal:4178)
  • ANNOUNCEMENT_DEV_SERVER - Announcement bar (e.g., host.docker.internal:4177)
  • LEXICAL_DEV_SERVER - Optional: Koenig Lexical editor preview server (e.g., host.docker.internal:4173)
    • Started by pnpm dev:lexical at the repo root, which runs koenig/koenig-lexical's dev:integrated target (editor rebuild watcher + vite preview on port 4173) and sets Admin's EDITOR_URL to point at it
    • Automatically falls back to Ghost backend (built package) if dev server is not running
  • ACTIVITYPUB_PROXY_TARGET - Optional: ActivityPub service (e.g., host.docker.internal:8080)
    • For developing with the ActivityPub project running locally
    • Requires the ActivityPub docker-compose services to be running

Note: Embedded React apps (activitypub) are served through the admin dev server so they don't need separate proxy entries.

Ghost Configuration

Ghost is configured via environment variables in compose.dev.yaml to load public app assets from /ghost/assets/* (e.g., portal__url: /ghost/assets/portal/portal.min.js). This uses the same path structure as built admin assets.

Routing Rules

The Caddyfile defines these routing rules:

Path PatternTargetPurpose
/ember-cli-live-reload.jsAdmin live reload (port 4200)Ember hot-reload script and WebSocket
/ghost/api/*Ghost backendGhost API (bypasses admin dev server)
/.ghost/activitypub/*ActivityPub server (port 8080)Optional: ActivityPub API (requires AP project running)
/.well-known/webfingerActivityPub server (port 8080)Optional: WebFinger for federation
/.well-known/nodeinfoActivityPub server (port 8080)Optional: NodeInfo for federation
/ghost/assets/koenig-lexical/*Lexical dev server (port 4173)Optional: Koenig editor via pnpm dev:lexical (falls back to Ghost)
/ghost/assets/portal/*Portal dev server (port 4175)Membership UI
/ghost/assets/comments-ui/*Comments dev server (port 7173)Comments widget
/ghost/assets/signup-form/*Signup dev server (port 6174)Signup form widget
/ghost/assets/sodo-search/*Search dev server (port 4178)Search widget (JS + CSS)
/ghost/assets/announcement-bar/*Announcement dev server (port 4177)Announcement widget
/ghost/assets/*Admin dev server (port 5174)Other admin assets — rewritten to /__admin-dev__/assets/*
/__admin-dev__/*Admin dev server (port 5174)Vite internals (HMR, modules, refresh runtime, dev-only assets)
/ghost, /ghost/Admin dev server (port 5174)Admin HTML entry — rewritten to /__admin-dev__/
/ghost/* (deep links)Ghost backendExpress middleware redirects deep links to /ghost/#/<path>
Everything elseGhost backendMain Ghost application

Note: All port numbers listed are the host ports where dev servers run by default.