Single-server self-hosting: instance-config refactor, selfhost deployment profile, fresh-install fixes

[flotob]

Goal

Make the complete Common Ground stack runnable on a single machine — 32 GB for a full production workload, 16 GB / 4–8 cores for a fresh instance — and make it easy for anyone to run CG locally or host their own instance.

Everything in this PR was validated on a real deployment: a fresh 8-core / 15 GiB Hetzner VPS now serves a fully working instance at https://cg.mogged.eu (built from this branch). Measured results below.

What's in here

1. Fresh-install fixes (0b6e48e)

Three things any new self-hoster hits on a clean machine:

• mediasoup workers crash on modern kernels — io_uring_queue_init(): Operation not permitted under Docker's seccomp. MEDIASOUP_DISABLE_LIBURING=true is now the dev default (and compose gives mediasoup no restart policy, so this failure was silent and permanent).
• hardhat container crash-loops — docker/hardhat/node/package.json had unpinned ts-node/typescript ranges and no lockfile; a fresh image build resolves an incompatible pair (readConfig 'fileExists' TypeError). Pinned.
• TokenSale dev deploy reverts — the cgstack branch of deploy.ts hardcoded an end timestamp of 2025-12-30, which is now in the past (OnlyFutureEndTimestampAllowed). Uses now+10y on the dev chain.

2. Instance identity decoupled from deployment mode (51e1d69)

Previously the app derived its mode and URLs from a hardcoded domain list — any domain other than app.cg/staging.app.cg silently ran with dev semantics, and several prod code paths were hard-broken on other domains:

• session cookie pinned to .app.cg → login impossible on other domains
• WebAuthn rpID pinned to id.app.cg → passkeys impossible
• sitemap URLs and email sender hardcoded

Self-hosted instances now declare their identity at serve time via an injected window.__CG_INSTANCE__ script (deployment mode, app URL, CG ID URL, reCAPTCHA site key). The API server injects it into the index.html it serves for share links; the selfhost nginx image injects it into the statically served copies. src/common/instance.ts is the typed accessor; config.ts/urls.ts consult it first and fall back to the legacy domain detection.

app.cg, staging.app.cg and local dev behave exactly as before when no instance config is injected — cookie domain, rpID and sitemap all derive to their previous values.

reCAPTCHA is now optional: with no keys configured, the frontend hides the widget and the backend skips verification (with a warning). Registration works out of the box on private instances; instances that want captcha set their own keys.

3. Self-hosting profile (51897aa, dba7dd7)

A production deployment path for one machine:

• docker/docker-compose.selfhost.yml — Caddy terminates TLS (automatic Let's Encrypt) for the app, the id. subdomain and mediasoup signalling (:4443); prod semantics on any domain; no hardhat/test contracts; postgres actually loads the tuned config; Redis capped at 512 MB each (was 2 GB); mediasoup auto-restarts.
• docker/selfhost/init.sh — one-shot init: fresh secrets, matching S3 credentials, internal certs. Never overwrites.
• docker/selfhost/selfhost.sh — build / up / down / logs / stats / update.
• docker/SELFHOST.md — setup guide, optional-integrations matrix, tuning, backups.

A self-hoster's whole journey: two DNS records → init.sh <domain> <email> → selfhost.sh build → selfhost.sh up.

4. Dev-stack fixes (d972d8b)

• postgresql.conf was mounted but never loaded (no -c config_file=) — all tuning in that file, including max_connections=200, was silently inert. Now wired up.
• updateFrontend.sh always died with a heap OOM: it ran craco without NODE_OPTIONS, and webpack needs ~3 GB (measured) against Node's ~2 GB default. Now 4 GB.
• Removed the orphan, unpassworded redis-blockscout (its only consumer is commented out); dropped obsolete compose version attributes.

5. Bugs found by testing the live instance (a62f40d)

• Community creation silently rolled back on fresh instances: the welcome-article template is a hardcoded prod article UUID that doesn't exist in a fresh DB; its failed INSERT aborted the whole creation transaction even though the error was caught. A savepoint now isolates the optional copy. This also protects app.cg — deleting that template article would break community creation the same way.
• Self-hosted instances no longer attempt to load CG's matomo analytics.
• Selfhost nginx: allow WASM compilation ('wasm-unsafe-eval' — web3 deps need it), SPA-shell fallback for deep links, /api/ws/ proxy, manifest-src 'self' for the CG ID manifest.

Measured results (8-core / 15 GiB VPS)

• Full source build: ~17 min; webpack peaks at ~3 GB RSS (the 8 GB heap in build.sh is 2.5× headroom; selfhost build uses 4 GB + no sourcemaps)
• Whole running stack (15 containers incl. Caddy): ~875 MiB RSS at idle
• Verified end-to-end on cg.mogged.eu: Let's Encrypt issuance, email signup (captcha-less), login, session cookie on the instance domain, community creation, socket.io, full WebAuthn passkey ceremony (rp.id correct for the instance, verified: true, cross-origin session shared with the CG ID popup) — the passkey flow was driven headless with a CDP virtual authenticator.

Not in scope / follow-ups

• Voice/video calls on the live instance not yet tested with real media (infrastructure verified: signalling TLS + UDP range reachable, 8 workers running)
• Email flows need a SendGrid key (graceful degradation verified); generic SMTP support would be the biggest self-hoster win
• Pre-built images (GHCR) to skip the source build
• Known pre-existing bug (untouched): previewImageUpdate job fails with column "imageId" does not exist

🤖 Generated with Claude Code

[flotob]

Two more commits from continued live testing on cg.mogged.eu:

2e11965 — Blockchain support without paid RPC providers. Testing Spark purchases surfaced that self-hosted instances had all onchain features broken: the frontend's Alchemy key is domain-locked to app.cg (CORS-fails everywhere else, leaving wallet flows stuck), and the backend's placeholder RPC endpoints made the onchain service crash-loop at startup (the premium-token bootstrap in startEventListener runs in an unhandled async IIFE — its NOT_SUPPORTED throw killed the process; that robustness fix matters for app.cg too). Now: the bootstrap degrades instead of crashing, init.sh prefills verified free public RPC endpoints (the QUIKNODE_* vars take any JSON-RPC URL), a single CG_ACTIVE_CHAINS env drives both backend chain workers and every chain picker in the UI, and self-hosted frontends use the chains' default public RPCs instead of the Alchemy key. Verified: premium token contract data (USDT/DAI/USDC) fetched via public endpoints, onchain stable.

2e30f6b — nginx resolves upstreams dynamically. nginx cached backend container IPs at startup, so every backend restart caused 502s/disconnects until nginx itself restarted. Docker-DNS resolver + variable proxy_pass (with set before rewrite ... break, which ends rewrite-phase processing) fixes updates-without-downtime. Verified across a live api container restart.

🤖 Generated with Claude Code

[flotob]

f349796 — Graceful degradation for every optional third-party service.

The server now derives capability flags from which secrets it actually has (features: {email, twitterAuth, kyc}, plus per-instance giphyApiKey / walletConnectProjectId) and ships them in the instance config; the UI hides or honestly labels what the instance can't do. Without an injected instance config every flag defaults to enabled, so app.cg/staging behavior is unchanged.

Highlights:

• No SendGrid: OTP login hidden (endpoint returns EMAIL_DISABLED instead of pretending a code was sent), verification modals never open, newsletter UI shows honest unavailable states, event RSVP no longer demands an unverifiable email, email jobs skip cleanly instead of process.exit(1).
• Robustness fixes that also protect app.cg: event RSVP/update/delete no longer return errors after the primary operation succeeded just because the notification email failed; the SumSub webhook ack survives email failures; the SendGrid error handler no longer crashes on errors without .response.
• No Twitter keys: X buttons hidden everywhere (previously a 500 in a popup). No SumSub: KYC steps say "not available on this instance" (previously an infinite spinner). No Mailchimp: newsletter preference stored locally instead of throwing UNKNOWN. Giphy: self-hosted instances no longer piggyback on CG's shared key. WalletConnect: project id per-instance (CG's is origin-allowlisted upstream).

Verified live on cg.mogged.eu: flags derived/injected correctly, X buttons gone from onboarding, zero console errors.

🤖 Generated with Claude Code

[flotob]

ac02a79 — publicnode restricted eth_getLogs; defaults replaced with verified endpoints.

The full self-hoster journey from SELFHOST.md was re-validated today on a freshly wiped server (same box, rebuilt from bare OS): install Docker → init.sh → selfhost.sh build (~17 min) → up. Let's Encrypt issuance, instance-config injection, socket.io, signup with the full WebAuthn passkey ceremony (headless CDP virtual authenticator: credentialAdded → verified true in ~150 ms) and community creation all work — the latter two also verified manually by a human on the live instance.

One regression surfaced since yesterday's validation, fixed here: every *.publicnode.com endpoint now rejects unfiltered eth_getLogs (-32701 "Please specify an address in your request"), which broke the onchain event listener on eth/matic/arbitrum (retry loops, no event processing). The new defaults were tested against the listener's real access pattern — unfiltered ranged getLogs over each chain's BLOCK_BATCHSIZE (40 blocks on arbitrum/nova, which rules out drpc's 10-block cap there, hence the official Arbitrum RPCs):

chain	old (broken)	new (verified)
eth	ethereum-rpc.publicnode.com	eth.drpc.org
matic	polygon-bor-rpc.publicnode.com	polygon.drpc.org
arbitrum	arbitrum-one-rpc.publicnode.com	arb1.arbitrum.io/rpc
bsc	bsc-rpc.publicnode.com	bsc.blockrazor.xyz
avax / optimism / linea / celo	*.publicnode.com	*.drpc.org
arbitrum nova	arbitrum-nova.publicnode.com	nova.arbitrum.io/rpc
xdai / base / fantom / zkevm / scroll / zksync	unchanged	unchanged (still work)

After the swap, all six active chains sync cleanly on cg.mogged.eu (eth processed 7135 watched-contract events on first sync, zero errors since). init.sh and SELFHOST.md now document the unfiltered-getLogs requirement so operators can test candidate endpoints before swapping them in.

Free public endpoints changing their policies under our feet is exactly the operational risk the optional-integrations matrix predicted — worth keeping the "test with an unfiltered eth_getLogs call" note in mind whenever a chain goes quiet.

🤖 Generated with Claude Code