Architectural Mandate: Formalized by Simple Agility Decision Log under decision SA-15 (Decided 2026-11-06 by Jake). This specification governs the extraction of shared business support services out of individual product applications into an autonomous, stack-level deployment plane located in repository
/backoffice.
In the Simple Agility Stack, product platforms such as Pressroom (customer communication), Wikantik (knowledge engineering), and Stockroom (commerce inventory) operate as sovereign, decoupled systems. Prior to release 0.7.2 of Pressroom, shared business services—specifically web analytics (Umami
) and newsletter distribution (Listmonk
)—were bundled directly within Pressroom's local Docker Compose deployment on host docker1.
Operating shared services inside a product repository introduces tight coupling: Pressroom maintained database lifecycles, backup routines, retention scripts, and superuser database credentials for tools that multiple applications across the stack consume. Under SA-15, all shared business services migrate to a dedicated Back-Office Suite deployed to repository /backoffice.
The suite is a stack-level sibling of the observability plane (SimpleAgilityObservabilityPlane). It owns the container orchestration, isolated PostgreSQL engines, persistent volumes, backup routines, and administrative provisioning for its tenants. Applications interact with back-office services purely as client consumers over standard HTTP APIs and private network channels.
flowchart TD
subgraph Edge_Ingress["Edge & Ingress (Host: cloudflare 192.168.5.50)"]
CF_TUNNEL["cloudflared Tunnel"]
PUB_ANALYTICS["analytics.wikantik.com"]
PUB_NEWSLETTER["newsletter.wikantik.com"]
PUB_ANALYTICS --> CF_TUNNEL
PUB_NEWSLETTER --> CF_TUNNEL
end
subgraph Product_Plane["Product Workloads (Host: docker1 192.168.5.51)"]
WIKANTIK["Wikantik (:8080)"]
PRESSROOM["Pressroom Caddy & App (:8084)"]
PROXY_TRACKER["Same-Origin /analytics/* Proxy"]
PRESSROOM --> PROXY_TRACKER
end
subgraph Backoffice_Suite["Back-Office Suite (Host: docker2 192.168.5.52 / ~/backoffice)"]
BO_CADDY["Back-Office Caddy Proxy (:8085)"]
UMAMI_SVC["Umami 3.3.0 Engine (:3000)"]
UMAMI_DB[("Umami PostgreSQL 18<br/>pressroom-umami-pgdata")]
LISTMONK_SVC["Listmonk Engine (:9000)"]
LISTMONK_DB[("Listmonk PostgreSQL 18<br/>pressroom-listmonk-pgdata")]
BACKUP_CRON["backoffice-backup Cron Loop"]
BO_CADDY --> UMAMI_SVC
BO_CADDY --> LISTMONK_SVC
UMAMI_SVC --- UMAMI_DB
LISTMONK_SVC --- LISTMONK_DB
BACKUP_CRON -.->|Nightly pg_dump| UMAMI_DB
BACKUP_CRON -.->|Nightly pg_dump| LISTMONK_DB
end
subgraph Observability["Observability Plane (Host: inference 192.168.5.53)"]
JAKEMON["jakemon Central"]
GRAFANA["Grafana Dashboards"]
GRAFANA -.->|Read-Only SQL via grafana_ro| UMAMI_DB
JAKEMON -.->|Scrape /metrics & Blackbox| BO_CADDY
end
CF_TUNNEL -->|Admin Dashboards| BO_CADDY
PROXY_TRACKER -->|LAN Telemetry Beacons| BO_CADDY
WIKANTIK -.->|Future LAN Proxy| BO_CADDY
The back-office suite is physically deployed to docker2 (192.168.5.52, docker2.lan). Deploying to docker2 redistributes compute and memory away from docker1, which is dedicated to high-traffic production workloads for Wikantik and Pressroom.
Following the architectural rules established in Home Lab Fleet and Ingress:
cloudflare (192.168.5.50). Public DNS routes analytics.wikantik.com and newsletter.wikantik.com terminate TLS at Cloudflare and forward plain HTTP to the back-office reverse proxy on docker2.docker2 exposes:
8085: Back-Office Caddy reverse proxy handling virtual hosts for analytics.wikantik.com and newsletter.wikantik.com.5434 / 5435: Optional loopback/LAN binds for database inspection if direct TCP access is required by Jakemon (otherwise accessed over Docker networks).analytics.wikantik.com. To protect reader privacy, circumvent restrictive client adblockers, and adhere to strict Content Security Policies (CSP), client applications proxy beacons same-origin. For example, Pressroom's edge Caddy on docker1 accepts /analytics/script.js and /analytics/api/send, proxying these requests internally over the LAN to http://docker2.lan:8085.docker2 is configured with trusted_proxies 192.168.5.50 192.168.5.51. This ensures that X-Forwarded-For and CF-Connecting-IP headers supplied by Cloudflare and client edge proxies are preserved, enabling Umami to calculate accurate geographic and visitor telemetry without IP masking.The seed implementation of the suite was originally drafted in Pressroom's docker-compose.backoffice.yml. In repository /backoffice, this configuration is fully decoupled from the Pressroom application image (ghcr.io/jakefearsd/pressroom). All maintenance tasks, database setup jobs, and backup loops run on standard, digest-pinned postgres:18 and alpine images with local shell scripts mounted via Compose volumes.
umami-db and listmonk-db) mounted to dedicated persistent volumes (backoffice-umami-pgdata and backoffice-listmonk-pgdata). A crash, migration failure, or maintenance lock on one service cannot impact the other.analytics_net: Connects umami, umami-db, and backoffice-backup.newsletter_net: Connects listmonk, listmonk-db, and backoffice-backup.ingress_net: Connects the back-office Caddy proxy to umami and listmonk.docker-compose.yml# /backoffice/docker-compose.yml
# Simple Agility Back-Office Suite: Umami & Listmonk (SA-15)
x-logging: &logging
driver: json-file
options:
max-size: "10m"
max-file: "5"
services:
caddy:
image: caddy:2.9-alpine
restart: unless-stopped
logging: *logging
ports:
- "8085:8085"
volumes:
- ./deploy/Caddyfile:/etc/caddy/Caddyfile:ro
- caddy-data:/data
- caddy-config:/config
networks:
- ingress_net
umami:
image: docker.umami.is/umami-software/umami@sha256:87312d334d009ee67ee0d2fba8fed01435547cc468e452243aef5133a9984d48
restart: unless-stopped
logging: *logging
depends_on:
umami-db:
condition: service_healthy
environment:
DATABASE_URL: postgresql://${UMAMI_DB_USER:-umami}:${UMAMI_DB_PASSWORD:?UMAMI_DB_PASSWORD required}@umami-db:5432/${UMAMI_DB:-umami}
DATABASE_TYPE: postgresql
APP_SECRET: ${UMAMI_APP_SECRET:?UMAMI_APP_SECRET required}
CLIENT_IP_HEADER: X-Forwarded-For
DISABLE_TELEMETRY: "1"
TRACKER_SCRIPT_NAME: script.js
networks:
- ingress_net
- analytics_net
umami-db:
image: postgres:18@sha256:4ef4dbc939d61acea57712655ddb4b4ab27419c913f94cca0cd57cb3ea3c2280
restart: unless-stopped
logging: *logging
environment:
POSTGRES_DB: ${UMAMI_DB:-umami}
POSTGRES_USER: ${UMAMI_DB_USER:-umami}
POSTGRES_PASSWORD: ${UMAMI_DB_PASSWORD:?UMAMI_DB_PASSWORD required}
volumes:
- backoffice-umami-pgdata:/var/lib/postgresql
- ./deploy/sql/umami-init.sql:/docker-entrypoint-initdb.d/01-init.sql:ro
healthcheck:
test: ["CMD-SHELL", "pg_isready -h 127.0.0.1 -U ${UMAMI_DB_USER:-umami} -d ${UMAMI_DB:-umami}"]
interval: 5s
timeout: 5s
retries: 20
networks:
- analytics_net
listmonk:
image: listmonk/listmonk:v4.1.0
restart: unless-stopped
logging: *logging
depends_on:
listmonk-db:
condition: service_healthy
environment:
LISTMONK_db__host: listmonk-db
LISTMONK_db__port: "5432"
LISTMONK_db__user: ${LISTMONK_DB_USER:-listmonk}
LISTMONK_db__password: ${LISTMONK_DB_PASSWORD:?LISTMONK_DB_PASSWORD required}
LISTMONK_db__database: ${LISTMONK_DB:-listmonk}
LISTMONK_db__ssl_mode: disable
LISTMONK_ADMIN_USER: ${LISTMONK_ADMIN_USER:-admin}
LISTMONK_ADMIN_PASSWORD: ${LISTMONK_ADMIN_PASSWORD:?LISTMONK_ADMIN_PASSWORD required}
networks:
- ingress_net
- newsletter_net
listmonk-db:
image: postgres:18@sha256:4ef4dbc939d61acea57712655ddb4b4ab27419c913f94cca0cd57cb3ea3c2280
restart: unless-stopped
logging: *logging
environment:
POSTGRES_DB: ${LISTMONK_DB:-listmonk}
POSTGRES_USER: ${LISTMONK_DB_USER:-listmonk}
POSTGRES_PASSWORD: ${LISTMONK_DB_PASSWORD:?LISTMONK_DB_PASSWORD required}
volumes:
- backoffice-listmonk-pgdata:/var/lib/postgresql
healthcheck:
test: ["CMD-SHELL", "pg_isready -h 127.0.0.1 -U ${LISTMONK_DB_USER:-listmonk} -d ${LISTMONK_DB:-listmonk}"]
interval: 5s
timeout: 5s
retries: 20
networks:
- newsletter_net
backoffice-backup:
image: postgres:18@sha256:4ef4dbc939d61acea57712655ddb4b4ab27419c913f94cca0cd57cb3ea3c2280
restart: unless-stopped
logging: *logging
user: "0:0"
depends_on:
umami-db:
condition: service_healthy
listmonk-db:
condition: service_healthy
volumes:
- backoffice-backups:/backups
- ./deploy/scripts/backup-loop.sh:/backup-loop.sh:ro
- ./deploy/sql/umami-retention.sql:/umami-retention.sql:ro
entrypoint: ["/bin/sh", "/backup-loop.sh"]
environment:
UMAMI_PGHOST: umami-db
UMAMI_DB_USER: ${UMAMI_DB_USER:-umami}
UMAMI_DB_PASSWORD: ${UMAMI_DB_PASSWORD}
UMAMI_DB: ${UMAMI_DB:-umami}
LISTMONK_PGHOST: listmonk-db
LISTMONK_DB_USER: ${LISTMONK_DB_USER:-listmonk}
LISTMONK_DB_PASSWORD: ${LISTMONK_DB_PASSWORD}
LISTMONK_DB: ${LISTMONK_DB:-listmonk}
BACKUP_HOUR: ${BACKUP_HOUR:-3}
BACKUP_RETENTION_DAYS: ${BACKUP_RETENTION_DAYS:-14}
UMAMI_RETENTION_DAYS: ${UMAMI_RETENTION_DAYS:-730}
networks:
- analytics_net
- newsletter_net
networks:
ingress_net:
analytics_net:
newsletter_net:
volumes:
caddy-data:
caddy-config:
backoffice-umami-pgdata:
backoffice-listmonk-pgdata:
backoffice-backups:
To maintain clean repository boundaries under SA-15, client applications (Pressroom, Wikantik, Stockroom) never access back-office databases with write permissions or manage service tables. Interaction is strictly mediated through HTTP APIs, client configuration, and read-only database grants.
Each client product is assigned a dedicated non-administrative service account within Umami:
umami-accounts.sql) on startup. It inserts dedicated user records (e.g., username: pressroom, username: wikantik) with bcrypt-hashed credentials and standard user roles.docs/dev/umami-api.md), client applications generate site IDs matching their own internal entity IDs (e.g., Umami website_id \equiv Pressroom weblog_id). A client reconciliation loop periodically verifies site registration using GET /api/websites/{id}, self-healing missing properties automatically.Browser telemetry avoids third-party tracking scripts. Client applications inject the tracking script via same-origin URLs:
<!-- Client Application Header (e.g., Pressroom or Wikantik) -->
<script async defer
src="/analytics/script.js"
data-website-id="0192e21b-4392-7104-9419-f5a1460d3d2c"
data-auto-track="true"
data-domains="blog.wikantik.com"></script>
Custom interaction events are tagged using declarative HTML5 attributes that Umami natively captures:
data-umami-event="cta-click"data-umami-event-entry="spring-boot-architecture"data-umami-event-dest="ebay.com"grafana_roWhile products write telemetry via Umami's HTTP ingest, stack-level observability tools and business reporting engines require structured SQL read access.
The back-office suite provisions a dedicated PostgreSQL role grafana_ro with SELECT permissions restricted to an unprivileged reporting view:
-- deploy/sql/umami-views.sql
-- Owned by Back-Office Suite; consumed by JakeMon Grafana & SimpleAgilityAttributionRFC
CREATE OR REPLACE VIEW analytics_traffic AS
SELECT
w.website_id,
w.name AS website_name,
e.created_at::date AS date,
e.url_path,
e.event_name,
COUNT(DISTINCT e.session_id) AS unique_visitors,
COUNT(*) AS total_events
FROM website_event e
JOIN website w ON e.website_id = w.website_id
GROUP BY w.website_id, w.name, e.created_at::date, e.url_path, e.event_name;
GRANT USAGE ON SCHEMA public TO grafana_ro;
GRANT SELECT ON analytics_traffic TO grafana_ro;
This view provides the foundation for marketing attribution joins defined in SimpleAgilityAttributionRFC, allowing Grafana dashboards on host inference to correlate blog reading volume with inventory sales in Stockroom without issuing expensive table scans across raw website_event partitions.
sequenceDiagram
autonumber
actor Reader as Site Reader (Browser)
participant Caddy as Client Edge Caddy (docker1)
participant BoCaddy as Backoffice Caddy (docker2)
participant Umami as Umami Engine (docker2)
participant DB as Umami PostgreSQL 18
participant Grafana as JakeMon Grafana (inference)
Reader->>Caddy: GET /analytics/script.js
Caddy->>BoCaddy: Proxy GET to http://docker2.lan:8085/script.js
BoCaddy->>Umami: Forward request
Umami-->>Reader: Return tracker JavaScript
Reader->>Caddy: POST /analytics/api/send (pageview beacon)
Note over Caddy: Injects CF-Connecting-IP & X-Forwarded-For
Caddy->>BoCaddy: Proxy POST to http://docker2.lan:8085/api/send
BoCaddy->>Umami: Ingest beacon
Umami->>DB: INSERT into website_event
loop Scheduled Reporting
Grafana->>DB: SELECT * FROM analytics_traffic WHERE date = TODAY
DB-->>Grafana: Aggregated visitor & CTA counts
end
Migrating Umami and Listmonk from docker1 to docker2 is executed via logical database streaming with zero structural data loss.
docker2/home/jakefear/source/backoffice on docker2./backoffice/.env:
UMAMI_APP_SECRET=$(openssl rand -hex 32)
UMAMI_DB_PASSWORD=$(openssl rand -hex 24)
LISTMONK_DB_PASSWORD=$(openssl rand -hex 24)
LISTMONK_ADMIN_PASSWORD=$(openssl rand -hex 24)
analytics.wikantik.com and newsletter.wikantik.com pointing to 192.168.5.52:8085.docker2 to initialize empty schemas:
docker compose up -d umami-db listmonk-db
docker1:
# Executed on docker1 inside Pressroom compose directory
docker compose exec umami-db pg_dump -U umami -Fc umami > /tmp/umami_docker1.dump
docker compose exec listmonk-db pg_dump -U listmonk -Fc listmonk > /tmp/listmonk_docker1.dump
docker2:
scp /tmp/umami_docker1.dump docker2.lan:/tmp/
scp /tmp/listmonk_docker1.dump docker2.lan:/tmp/
docker2 database engines:
# Executed on docker2
docker compose exec -T umami-db pg_restore -U umami -d umami --clean /tmp/umami_docker1.dump
docker compose exec -T listmonk-db pg_restore -U listmonk -d listmonk --clean /tmp/listmonk_docker1.dump
grafana_ro user creation and reporting view scripts:
docker compose exec -T umami-db psql -U umami -d umami < deploy/sql/umami-views.sql
docker2:
docker compose up -d
docker1 in /opt/pressroom/.env:
# Redirect internal API and Caddy reverse proxy to docker2.lan
PRESSROOM_ANALYTICS_UMAMI_APIURL=http://docker2.lan:8085
PRESSROOM_NEWSLETTER_LISTMONK_BASEURL=http://docker2.lan:8085
docker-compose.backoffice.yml from COMPOSE_FILE in Pressroom's .env, and reload Pressroom:
docker compose up -d --remove-orphans
docker1 to confirm successful token refresh via POST http://docker2.lan:8085/api/auth/login.blog.wikantik.com/analytics/api/send return 200 OK from docker2.https://analytics.wikantik.com via Cloudflare Zero Trust authentication and verify that historical visitor graphs match pre-migration statistics.Following the safety precedent established in Pressroom's database isolation work:
docker1 (pressroom-umami-pgdata and pressroom-listmonk-pgdata) are left completely intact for 14 days..env and restarting the local overlay.docker1.Operating shared services across host boundaries introduces failure modes that do not exist in single-host deployments.
| Failure Mode | Root Cause | Impact | Mitigation & Recovery |
|---|---|---|---|
| Cross-Host LAN Partition | Ethernet switch disruption or DHCP/IP drift between docker1 and docker2. | Pressroom blogs fail to record analytics; newsletter subscription forms yield 503 errors. Blog page delivery remains unaffected. | Pressroom's UmamiClient executes with strict 3-second connect timeouts and fails open. Reader page loads are never blocked. Alertmanager fires BlackboxProbeFailed on docker2.lan. Reconnect network interface or verify static ARP. |
| IP Anonymization / Geolocation Failure | Caddy reverse proxy fails to forward client IP headers or omits trusted_proxies. | Umami records all reader sessions as originating from 192.168.5.50 (cloudflare) or 192.168.5.51 (docker1). | Caddy configuration pins trusted_proxies 192.168.5.50/32 192.168.5.51/32. Umami environment variable CLIENT_IP_HEADER=X-Forwarded-For is pinned in Compose. Automated integration test inspects incoming headers against known loopback IPs. |
| Database Disk Saturation | High reader traffic accumulates raw website_event rows over extended operating cycles. | PostgreSQL transactions fail; Umami rejects incoming beacons with HTTP 500. | The backoffice-backup service executes an automated retention pruning job (umami-retention.sql) nightly following backup completion. Partitions older than UMAMI_RETENTION_DAYS (default: 730 days) are truncated. |
| Adblocker Interception | Readers enable strict browser tracker blocking (uBlock Origin, Brave Shields). | Analytics undercount page views and conversion events. | Mitigated by design: trackers are served same-origin from the primary blog domain (/analytics/script.js), and beacon payloads are sent to /analytics/api/send. The script filename is configurable via TRACKER_SCRIPT_NAME. |
| Token Invalidation on Password Rotation | Operator rotates UMAMI_PRESSROOM_PASSWORD in the database without restarting Pressroom. | Pressroom background reconciliation threads receive HTTP 401 on POST /api/websites. | Pressroom's UmamiClient detects 401 responses, automatically triggers re-authentication against POST /api/auth/login, and caches the new bearer token without requiring an application restart. |
website_event tables and grafana_ro SQL joins.docker2.lan.