Self-Hosted Vendor Stacks (On-Prem)

By default, the CTMS platform connects to Supabase Cloud (authentication) and Frappe Cloud (clinical backend). For on-premises deployments where cloud connectivity is not available or not desired, both vendor stacks can be self-hosted using Docker Compose.

When Is This Needed?

Self-hosting is optional. You only need this guide if:

Your deployment environment has no internet access
Regulatory or data residency requirements prohibit cloud services
You want a fully self-contained local development environment

If you use Supabase Cloud + Frappe Cloud, skip this page entirely — proceed to Initial Setup & Configuration.

Architecture Overview

All three stacks — Supabase, Frappe, and CTMS core — share a single Docker bridge network called ctms-network, enabling container-to-container communication by name.

┌──────────────────────── ctms-network (bridge) ─────────────────────────────┐
│                                                                            │
│  ┌─ Supabase (13 svc) ──┐  ┌─ Frappe (12 svc) ──┐  ┌─ CTMS Core ──────┐  │
│  │ kong, db, auth,       │  │ frontend, backend,  │  │ caddy, krakend,  │  │
│  │ rest, realtime,       │  │ db (MariaDB),        │  │ zynexa, sublink, │  │
│  │ storage, studio,      │  │ redis, websocket,   │  │ cube, mcp, odm,  │  │
│  │ analytics, vector,    │  │ scheduler, queues,  │  │ lakehouse, otel  │  │
│  │ edge-functions, ...   │  │ setup (init)        │  │                  │  │
│  └───────────────────────┘  └─────────────────────┘  └──────────────────┘  │
│                                                                            │
│  ┌─ CTMS Init Containers (one-shot, always required) ─────────────────────┐│
│  │ ctms-supabase-seed  → CTMS tables in Supabase (profiles, devices, ...) ││
│  │ ctms-init           → Frappe DocTypes, RBAC, seed data (5 stages)      ││
│  └────────────────────────────────────────────────────────────────────────┘│
└────────────────────────────────────────────────────────────────────────────┘

Startup Order

The vendor stacks must be started before CTMS core services:

Supabase (creates ctms-network)
Frappe (joins ctms-network; setup service generates API token)
CTMS Init (supabase-seed + ctms-init provision custom data)
CTMS Core (zynexa, sublink, cube, etc.)

Separation of Concerns

Container	Scope	When to Run
Supabase stack	Vendor — runs the auth platform exactly as distributed	On-prem Supabase only
Frappe stack	Vendor — runs ERPNext/Healthcare exactly as distributed	On-prem Frappe only
Frappe `setup` service	CTMS — completes wizard, creates admin, generates API token	On-prem Frappe only
`ctms-supabase-seed`	CTMS — creates profiles, devices, medication_logs, notification_logs tables + RLS	Always (cloud or on-prem)
`ctms-init`	CTMS — provisions 34 DocTypes, 15 custom fields, 539 RBAC records (incl. 4 Frappe native roles), 88 seed records, 1 practitioner	Always (cloud or on-prem)

Vendor Purity

The vendor Docker Compose files (supabase/docker-compose.yml and frappe-marley-health/docker-compose.yml) are kept unmodified from their upstream distributions. All CTMS-specific customizations are applied via separate init containers — this ensures clean vendor upgrades.

Prerequisites

Docker Engine 24+ and Docker Compose v2
Docker Buildx >= 0.10 — required to build the Frappe image (see below)
At least 8 GB RAM available for Docker (Supabase alone needs ~4 GB)
Ports available: 8000 (Supabase API), 8080 (Frappe), plus CTMS ports

Installing Docker Buildx on Linux Servers

Docker Desktop (macOS / Windows) includes Buildx by default. On Linux servers (e.g., Amazon Linux, Ubuntu), install it separately:

# Amazon Linux 2023 / RHEL / Fedora
BUILDX_VERSION=$(curl -s https://api.github.com/repos/docker/buildx/releases/latest | jq -r '.tag_name')
sudo mkdir -p /usr/local/lib/docker/cli-plugins
sudo curl -SL "https://github.com/docker/buildx/releases/download/${BUILDX_VERSION}/buildx-${BUILDX_VERSION}.linux-amd64" \
    -o /usr/local/lib/docker/cli-plugins/docker-buildx
sudo chmod +x /usr/local/lib/docker/cli-plugins/docker-buildx

# Verify
docker buildx version

Buildx is required because the Frappe Dockerfile runs bench get-app during image build, which uses BuildKit features.

Step 1: Self-Hosted Supabase

1.1 Configure Environment

cd ctms.devops/supabase
cp .env.sample .env

Edit .env and change the default secrets:

Variable	Default	Action
`POSTGRES_PASSWORD`	`your-super-secret-and-long-postgres-password`	Change in production
`JWT_SECRET`	`super-secret-jwt-token-with-at-least-32-characters-long`	Change in production
`ANON_KEY`	Pre-generated JWT	Regenerate for production (guide)
`SERVICE_ROLE_KEY`	Pre-generated JWT	Regenerate for production
`DASHBOARD_USERNAME`	`ctms_user`	Dashboard login
`DASHBOARD_PASSWORD`	`ctms_pwd`	Dashboard login

1.2 Start Supabase

docker compose up -d

Wait for all 13 services to become healthy:

docker compose ps --format "table {{.Name}}\t{{.Status}}"

Expected: All services show Up (healthy) except realtime which may show Up (unhealthy) — this is a known Supabase self-hosted issue and does not affect functionality.

1.3 Seed CTMS Tables (Required for All Deployments)

note

The ctms-supabase-seed container is required for both cloud and self-hosted Supabase. It creates the CTMS-specific tables (profiles, devices, medication_logs, notification_logs) and RLS policies that the application depends on. For cloud Supabase, run this against your managed database URL.

After Supabase is healthy, run the CTMS seed container from the root ctms.devops directory:

cd ctms.devops
docker compose --env-file .env.local --profile init run --rm --build ctms-supabase-seed

This creates:

profiles table (linked to auth.users via trigger)
devices table
medication_consumption_logs table
notification_logs table
get_medication_status() function
Row-Level Security policies on all tables

Expected output: Total: 5 | OK: 5 | Failed: 0

1.4 Update Root Environment

Copy these values from supabase/.env into your root .env.local / .env.production:

# Point to on-prem Supabase (container name on ctms-network)
SUPABASE_URL=http://supabase-kong:8000
SUPABASE_KEY=<SERVICE_ROLE_KEY from supabase/.env>
SUPABASE_ANON_KEY=<ANON_KEY from supabase/.env>
DATABASE_URL=postgresql://postgres:<POSTGRES_PASSWORD>@supabase-db:5432/postgres

1.5 Verify

# Studio dashboard
open http://localhost:8000

# API health
curl -s http://localhost:8000/rest/v1/ \
  -H "apikey: <ANON_KEY>" \
  -H "Authorization: Bearer <ANON_KEY>"

Step 2: Self-Hosted Frappe

2.1 Configure Environment

cd ctms.devops/frappe-marley-health
cp .env.sample .env

Key variables:

Variable	Default	Description
`ADMIN_PASSWORD`	`Welcome@1234`	Frappe Administrator password
`ADMIN_EMAIL`	`admin@myfrappe.com`	Admin user email
`COMPANY_NAME`	`CTMS`	Organization name for setup wizard
`SITE_NAME`	`frontend`	Frappe site name (usually keep as `frontend`)

2.2 Start Frappe

docker compose up -d

The startup sequence is:

configurator — generates Frappe configuration files → exits
create-site — creates the MariaDB database and site → exits
setup — completes the setup wizard, creates admin user, generates API keys → exits
backend, frontend, websocket, queues, scheduler — start and run

2.3 Retrieve the API Token

The setup service automatically generates an API token. Retrieve it:

# From the setup container logs
docker logs frappe-marley-health-setup-1 2>&1 | grep FRAPPE_API_TOKEN

# Or from the shared file
docker exec frappe-marley-health-backend-1 \
  cat /home/frappe/frappe-bench/sites/api_token.txt

2.4 Update Root Environment

Copy the generated token into your root .env.local / .env.production:

# Point to on-prem Frappe (container name on ctms-network)
FRAPPE_URL=http://frappe-marley-health-frontend-1:8080
FRAPPE_API_TOKEN="<key>:<secret>"
FRAPPE_CLOUD_IMAGE_BASE_URL=http://frappe-marley-health-frontend-1:8080

2.5 Verify

# Frappe dashboard
open http://localhost:8080/app

# API health check using the generated token
curl -s -H "Authorization: token <key>:<secret>" \
  http://localhost:8080/api/method/frappe.auth.get_logged_user
# Expected: {"message":"admin@myfrappe.com"}

Step 3: Regenerate API Token (CLI)

If you need to regenerate the Frappe API token at any time (e.g., after a secret rotation or security incident):

docker exec -w /home/frappe/frappe-bench frappe-marley-health-backend-1 \
  bash -c 'source env/bin/activate && python3 /setup/frappe-generate-token.py'

Output:

FRAPPE_API_TOKEN="<new_key>:<new_secret>"

  User:   admin@myfrappe.com
  Key:    <api_key>
  Secret: <new_secret>
  File:   /home/frappe/frappe-bench/sites/api_token.txt

After regeneration, update FRAPPE_API_TOKEN in your .env.local / .env.production and restart CTMS services that depend on it:

# Restart services that use FRAPPE_API_TOKEN
docker compose --env-file .env.local up -d zynexa api-gateway

warning

Token regeneration changes the API secret while preserving the API key. Any running ctms-init or other service using the old token will need the updated value.

Step 4: Run CTMS Init (Required for All Deployments)

After both vendor stacks are running and the API token is configured, provision Frappe with the CTMS data model:

cd ctms.devops
docker compose --env-file .env.local --profile init up ctms-init

This runs the 5-stage provisioning:

Stage	Creates	Count
1	Custom DocTypes	34
2	Custom Fields on built-in DocTypes	15
3	RBAC data (Frappe native roles, CTMS roles, resources, permissions)	539
4	Master/seed data (lookups, drugs, lab items)	88
5	Default Healthcare Practitioner	1

This Step Is Always Required

Both ctms-supabase-seed and ctms-init are required regardless of whether you use cloud or self-hosted vendor services. They create the CTMS data model (Supabase tables + Frappe DocTypes + default practitioner) that the application depends on.

After Stage 5 completes, copy the generated NEXT_PUBLIC_DEFAULT_PRACTITIONER_ID into your .env file.

Step 5: Start CTMS Core Services

cd ctms.devops
docker compose --env-file .env.local up -d

Verify cross-stack connectivity:

# Zynexa → Frappe
docker exec ctms-zynexa curl -sf http://frappe-marley-health-frontend-1:8080/api/method/frappe.auth.get_logged_user \
  -H "Authorization: token <FRAPPE_API_TOKEN>"

# Zynexa → Supabase
docker exec ctms-zynexa curl -sf http://supabase-kong:8000/rest/v1/ \
  -H "apikey: <ANON_KEY>"

Complete On-Prem Startup Sequence

Here is the full end-to-end sequence for a clean on-prem deployment:

cd ctms.devops

# 1. Start Supabase (creates ctms-network)
cd supabase && docker compose up -d && cd ..

# 2. Seed CTMS tables into Supabase (required for ALL deployments)
docker compose --env-file .env.local --profile init run --rm --build ctms-supabase-seed

# 3. Start Frappe (setup service auto-completes wizard + generates API token)
cd frappe-marley-health && docker compose up -d && cd ..

# 4. Retrieve the generated API token
docker logs frappe-marley-health-setup-1 2>&1 | grep FRAPPE_API_TOKEN
# → Update FRAPPE_API_TOKEN in .env.local

# 5. Provision Frappe with CTMS data model (5 stages)
docker compose --env-file .env.local --profile init up ctms-init
# → Copy NEXT_PUBLIC_DEFAULT_PRACTITIONER_ID from Stage 5 output into .env.local

# 6. Start CTMS core services
docker compose --env-file .env.local up -d

# 7. (Optional) Start analytics + observability
docker compose --env-file .env.local --profile analytics --profile observability up -d

Stopping (Reverse Order)

# CTMS core
docker compose --env-file .env.local down

# Frappe
cd frappe-marley-health && docker compose down && cd ..

# Supabase (last — owns ctms-network)
cd supabase && docker compose down && cd ..

Data Volumes

Use docker compose down (without -v) to preserve data. Adding -v destroys all database volumes and requires re-running the full setup sequence.

Troubleshooting

Problem	Cause	Fix
`ctms-supabase-seed` fails with `auth.jwt() does not exist`	GoTrue (auth service) not ready	The seed container waits automatically; if it still fails, ensure `supabase-auth` is healthy
`ctms-init` fails with connection refused	Frappe not ready or wrong token	Check `FRAPPE_URL` and `FRAPPE_API_TOKEN` in `.env.local`
User signup fails with `LinkValidationError: Could not find Role`	Frappe native Role entries missing (Stage 3 not run or outdated image)	Re-run Stage 3: `CTMS_INIT_STAGES=3 docker compose --env-file .env.local --profile init run --rm ctms-init`
Supabase `realtime` shows unhealthy	Known self-hosted issue with tenant auth	Non-blocking — realtime works through Kong
Network `ctms-network` not found	Supabase not started first	Start Supabase before other stacks, or create manually: `docker network create ctms-network`
Frappe `setup` exits with code 1	Missing log directories	Ensure the setup service has the `logs` volume mounted

Architecture Overview​

Startup Order​

Separation of Concerns​

Prerequisites​

Step 1: Self-Hosted Supabase​

1.1 Configure Environment​

1.2 Start Supabase​

1.3 Seed CTMS Tables (Required for All Deployments)​

1.4 Update Root Environment​

1.5 Verify​

Step 2: Self-Hosted Frappe​

2.1 Configure Environment​

2.2 Start Frappe​

2.3 Retrieve the API Token​

2.4 Update Root Environment​

2.5 Verify​

Step 3: Regenerate API Token (CLI)​

Step 4: Run CTMS Init (Required for All Deployments)​

Step 5: Start CTMS Core Services​

Complete On-Prem Startup Sequence​

Stopping (Reverse Order)​

Troubleshooting​