Service helper that provisions a Matrix-ready box with:
  • PostgreSQL (5432)
  • Synapse client/federation API (8080, bound on 0.0.0.0)

​
Quick Start

forkr-matrix new my-matrix
forkr-matrix connect-db my-matrix
new waits for Postgres (5432) and Synapse (8080) before returning.

​
Create

forkr-matrix new my-matrix
What it sets up:
  • Box tag: service=matrix
  • Single data volume mounted at /var/lib/matrix
  • PostgreSQL data: /var/lib/matrix/postgres
  • Synapse config/state: /var/lib/matrix/synapse
  • Public registration disabled by default (enable_registration: false)
To bind Matrix to a real public name from the start: 
forkr-matrix new my-matrix --hostname chat.example.com
This publishes the box at chat.example.com and initializes Synapse with:
  • server_name: chat.example.com
  • public_baseurl: https://chat.example.com/

​
Connect (Postgres)

forkr-matrix connect-db my-matrix
Pass extra psql args after --: 
forkr-matrix connect-db my-matrix -- -c "select now()"
Defaults:
  • User: postgres
  • Database: postgres
  • Password: postgres

​
Create User (Admin Path)

With public registration disabled, create users via the service command: 
forkr-matrix new-user my-matrix alice --password 'dev-pass'
forkr-matrix new-user my-matrix admin --password 'admin-pass' --admin
This runs inside the box and uses Synapse admin registration tooling.

​
Get Access Token

forkr-matrix get-access-token my-matrix \
  --user '@alice:chat.example.com' \
  --password 'dev-pass'
This logs in via /_matrix/client/v3/login and prints only the access token. By default it uses the first published domain for the matrix box, falling back to Box API URL metadata. Use an explicit hostname or URL: 
forkr-matrix get-access-token my-matrix \
  --hostname chat.example.com \
  --user '@alice:chat.example.com' \
  --password 'dev-pass'

forkr-matrix get-access-token my-matrix \
  --url https://chat.example.com \
  --user '@alice:chat.example.com' \
  --password 'dev-pass' \
  --json

​
Matrix API Smoke Check

4kr exec my-matrix --project <project> -- \
  curl -fsS http://127.0.0.1:8080/_matrix/client/versions

​
Public URL Smoke Check

4kr list --project <project>
# then hit the box URL from list:
curl -fsS "https://<box-url-from-list>/_matrix/client/versions"
Synapse client discovery (/.well-known/matrix/client) is configured to advertise this public URL. Initial value comes from Box API url metadata (box/domain aware).

​
Publish (Custom Public Name)

forkr-matrix publish my-matrix my-chat
This:
  • runs 4kr publish
  • resolves the real published hostname from Box API metadata
  • updates Synapse public_baseurl so /.well-known/matrix/client points at the published URL.
With explicit domain override: 
forkr-matrix publish my-matrix my-chat --domain example.com
Or publish directly to an exact hostname: 
forkr-matrix publish my-matrix --hostname chat.example.com

​
Snapshot + Box

forkr-matrix snapshot my-matrix
forkr-matrix box my-matrix my-matrix-copy
Box snapshots/restores Postgres + Synapse state together because they share one mounted data volume.

​
Stop

forkr-matrix stop my-matrix
Performs clean stops for:
  • Synapse process
  • PostgreSQL (CHECKPOINT + smart shutdown)

​
E2E Verification (Bot + Room + Second Instance)

Run: 
./crates/forkr-matrix/verify.sh
This verifies real usage, not just infra plumbing:
  1. Creates matrix-A and confirms Matrix API is live.
  2. Creates bot and human users via forkr-matrix new-user.
  3. Bot creates a room and sends a message.
  4. Human user reads the event from the room.
  5. Boxes to matrix-B.
  6. Bot logs into the second instance and sends another message.
  7. Human user on the second instance reads both the pre-box and post-box messages.
It also validates forkr-matrix list tag filtering and forkr-matrix delete cleanup.