### Start MCP Server (Shell)

Source: https://docs.zynomi.com/architecture/analytics-ai-integration

Starts the MCP server by navigating to its directory, installing dependencies, and running the server.

```shell
cd ctms-mcp-server
pip install -r requirements.txt
make run
```

--------------------------------

### Configure install.conf for Deployment

Source: https://docs.zynomi.com/deployment/single-click-deployment

Copies the example configuration file and edits it with server-specific details for the installer. This includes server host, user, SSH authentication method, and GitHub token.

```bash
cd scripts
cp install.conf.example install.conf
```

--------------------------------

### Start Cube.js (Shell)

Source: https://docs.zynomi.com/architecture/analytics-ai-integration

Starts the Cube.js service by navigating to its directory, installing Node.js dependencies, and running the development server.

```shell
cd ctms-semantic-cube
npm install
npm run dev
```

--------------------------------

### Start Web App (Shell)

Source: https://docs.zynomi.com/architecture/analytics-ai-integration

Starts the web application by navigating to its directory and running the development server using Bun.

```shell
cd ctms-web
bun run dev
```

--------------------------------

### Clone Repository and Initialize Environment

Source: https://docs.zynomi.com/deployment/installation

Commands to clone the deployment repository and create the necessary environment configuration files from the provided template.

```bash
git clone https://github.com/zynomilabs/ctms.devops.git && cd ctms.devops
cp .env.example .env.production
ln -sf .env.production .env
```

--------------------------------

### Analyze Deploy Log for Frappe Setup

Source: https://docs.zynomi.com/recipes/deployment-verification

This command searches the deployment log file for lines indicating the start of Frappe setup and displays the following two lines to confirm critical milestones. It helps in verifying if the Frappe setup process has begun and is progressing.

```bash
grep -A2 "Waiting for Frappe setup" /tmp/deploy-*.log
```

--------------------------------

### GET /readyz

Source: https://docs.zynomi.com/deployment/single-click-deployment

Checks the readiness status of the Cube.js analytics service.

```APIDOC
## GET /readyz

### Description
Verifies that the Cube.js analytics service is ready to process queries.

### Method
GET

### Endpoint
http://localhost:4000/readyz

### Response
#### Success Response (200)
- **health** (string) - The readiness status of the service.

#### Response Example
{
  "health": "RESPOND"
}
```

--------------------------------

### Example install.conf Configuration

Source: https://docs.zynomi.com/deployment/single-click-deployment

Illustrates the structure and key parameters within the install.conf file. It shows settings for server connection, SSH authentication (key, password, local mode), deployment path, and GitHub integration.

```bash
# Server connection
SERVER_HOST=203.0.113.50          # Your server's public IP
SERVER_USER=ec2-user              # SSH user (ec2-user, rocky, root)

# ─── SSH Authentication (choose one method) ───────────────
# Option 1: Key-based authentication (default)
SSH_KEY=./ssh-keys/ec2-prd.pem    # Path to SSH private key

# Option 2: Password-based authentication
#SSH_PASSWORD=your_password
#SSH_AUTH_METHOD=password

# Option 3: Local mode (run directly on server, no SSH)
#LOCAL_MODE=true

# Deployment
DEPLOY_PATH=/opt/ctms-deployment
ENV_FILE=.env.production

# GitHub (for code sync to server)
GITHUB_REPO=zynomilabs/ctms.devops
GITHUB_TOKEN=ghp_xxxxxxxxxxxx
```

--------------------------------

### Step-by-Step CTMS Deployment (Shell)

Source: https://docs.zynomi.com/deployment/bundle-deployment

Provides a step-by-step method for deploying the CTMS platform. It includes bootstrapping the system (installing Docker and dependencies), exiting and re-logging in, and then executing the full deployment script. Requires root or sudo access.

```shell
./zynctl.sh bootstrap    # Install Docker, Compose, system tuning  
exit                      # Re-login for Docker group membership  
ssh root@<server-ip>  
cd zynctl-bundle-<version>  
./zynctl.sh deploy        # Full 12-step deploy  
```

--------------------------------

### Start Docker Compose Services with Profiles

Source: https://docs.zynomi.com/deployment/docker-deployment-guide

Commands to start Docker Compose services using different profiles. The `--env-file` flag specifies the environment configuration, and `--profile` selects specific service groups. This allows for flexible deployment of core, analytics, lakehouse, and observability services.

```bash
# Core only
docker compose --env-file .env.production up -d

# Core + Analytics + AI
docker compose --env-file .env.production --profile analytics up -d

# Full stack
docker compose --env-file .env.production \
  --profile analytics --profile lakehouse --profile observability up -d

```

--------------------------------

### Start Analytics Stack Locally

Source: https://docs.zynomi.com/architecture/analytics-ai-integration

Shell commands to clone the monorepo, configure environment variables, and launch the full stack using the provided Makefile.

```bash
git clone git@github.com:zynomilabs/ctms-data-pipeline-ai-analytics.git
cd ctms-data-pipeline-ai-analytics
cp .env.production .env
make stack
```

--------------------------------

### Docker Compose Basic Profile Commands

Source: https://docs.zynomi.com/deployment/docker-compose-profiles

Demonstrates how to start specific Docker Compose profiles or combinations of profiles. These commands allow selective deployment of services, such as the 'core' or 'analytics' stacks, or the entire platform using the 'all' profile.

```bash
docker compose --profile core up -d

docker compose --profile analytics up -d

docker compose --profile core --profile analytics up -d

docker compose --profile all up -d
```

--------------------------------

### Docker Compose Multi-file Configuration Example

Source: https://docs.zynomi.com/deployment/docker-compose-profiles

Illustrates how to use multiple Docker Compose configuration files with profiles. This allows for environment-specific configurations, such as merging a base 'docker-compose.yml' with a 'docker-compose.prod.yml' for production deployments.

```bash
docker compose -f docker-compose.yml -f docker-compose.prod.yml --profile all up -d
```

--------------------------------

### Configure Environment and Python Dependencies

Source: https://docs.zynomi.com/deployment/initial-setup-and-configuration

Setup steps for manual provisioning, including environment variable configuration and Python virtual environment initialization.

```bash
# Environment configuration
FRAPPE_URL=https://your-frappe-instance.frappe.cloud
FRAPPE_API_TOKEN=api-key:api-secret

# One-time setup
cd ctms.devops/scripts/frappe-seed
python -m venv venv
source venv/bin/activate
pip install requests python-dotenv structlog
```

--------------------------------

### Password-Based SSH Configuration Example

Source: https://docs.zynomi.com/deployment/single-click-deployment

Shows how to configure the install.conf file for password-based SSH authentication. This requires setting the SERVER_HOST, SERVER_USER, SSH_PASSWORD, and SSH_AUTH_METHOD variables.

```bash
SERVER_HOST=203.0.113.50
SERVER_USER=admin
SSH_PASSWORD=your_secure_password
SSH_AUTH_METHOD=password
```

--------------------------------

### Build and Deploy API Gateway

Source: https://docs.zynomi.com/deployment/installation

Docker Compose commands to build the KrakenD API gateway locally and manage its lifecycle within the production environment.

```bash
docker compose --env-file .env.production build api-gateway
docker compose --env-file .env.production build api-gateway && \
docker compose --env-file .env.production up -d api-gateway
```

--------------------------------

### Local Mode Deployment on Server

Source: https://docs.zynomi.com/deployment/single-click-deployment

Demonstrates how to execute the installer directly on the target server when SSH is not available or desired. This involves copying the repository and running the script with LOCAL_MODE=true.

```bash
# On the server
cd /opt/ctms.devops/scripts
LOCAL_MODE=true ./install.sh deploy
```

--------------------------------

### Run development servers for Cube.js and Web app

Source: https://docs.zynomi.com/architecture/dashboard-development

Commands to start the development environment. Requires navigating to the respective project directories and executing the start scripts for Cube.js and the web application.

```bash
# Terminal 1: Cube.js
cd ctms-semantic-cube && npm run dev

# Terminal 2: Web app
cd ctms-web && bun run dev
```

--------------------------------

### Install Deployment Verification Utility

Source: https://docs.zynomi.com/recipes/deployment-verification

Command to download and install the verification script as a globally executable command on the server.

```bash
curl -sL https://raw.githubusercontent.com/zynomi/ctms.devops/main/scripts/verify-deployment.sh -o /usr/local/bin/ctms-verify && chmod +x /usr/local/bin/ctms-verify
```

--------------------------------

### Manage Service Lifecycle and Logs

Source: https://docs.zynomi.com/deployment/docker-compose-profiles

Standard commands for starting, stopping, and monitoring Zynomi services. Includes options for tailing logs and managing service state via profiles.

```bash
# Starting Services
docker compose --profile core up -d
docker compose -f docker-compose.yml -f docker-compose.prod.yml --profile all up -d

# Viewing Logs
docker compose logs -f
docker compose logs -f zynexa
docker compose logs --tail=100 -f

# Service Management
docker compose down
docker compose down -v
docker compose restart zynexa
docker compose ps
```

--------------------------------

### Deploy CTMS Platform with install.sh

Source: https://docs.zynomi.com/deployment/single-click-deployment

Executes the main installation script to deploy the complete CTMS platform. This is the primary command for initiating the deployment process.

```bash
./install.sh deploy
```

--------------------------------

### Triggering GitHub Actions Workflow via CLI

Source: https://docs.zynomi.com/architecture/installer-bundle

This example shows how to trigger a GitHub Actions workflow named 'build-install-bundle.yml' from the command line using the 'gh' CLI. It includes options for a default reason, a custom reason, and watching the workflow run.

```bash
cd ctms.devops  

# Trigger with default reason  
gh workflow run build-install-bundle.yml  

# Trigger with a custom reason  
gh workflow run build-install-bundle.yml -f reason="Hotfix: refresh-token command added"  

# Watch the run  
gh run watch  
```

--------------------------------

### Configure Production Environment File

Source: https://docs.zynomi.com/deployment/single-click-deployment

Copies the example environment file and prepares it for production settings. This file contains critical variables for the CTMS application stack.

```bash
# Copy the template and fill in your values
cp .env.example .env.production
```

--------------------------------

### Cube.dev SQL API Example

Source: https://docs.zynomi.com/architecture/cube-semantic-layer

An example of how to query the Cube.dev semantic layer using SQL, compatible with PostgreSQL clients.

```APIDOC
## SQL API

### Description
Connect via psql to port 15432 to query the semantic layer using SQL.

### Method
SQL (via PostgreSQL protocol)

### Endpoint
`[host]:15432`

### Request Example
```sql
-- Connect via psql to port 15432
SELECT
  study_name,
  COUNT(*) as enrollments
FROM Enrollments
GROUP BY study_name
ORDER BY enrollments DESC;
```

### Response
#### Success Response (200)
- Results are returned in a standard SQL result set format.

#### Response Example
```
study_name | enrollments
------------|------------
Study A     | 100
Study B     | 150
```
```

--------------------------------

### Install Docker Buildx on Linux

Source: https://docs.zynomi.com/deployment/self-hosted-vendor-stacks

A shell script to fetch the latest Docker Buildx binary from GitHub, install it as a CLI plugin, and verify the installation. This is a prerequisite for building the Frappe Docker image on Linux servers.

```bash
# 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
```

--------------------------------

### Execute Provisioning Scripts

Source: https://docs.zynomi.com/deployment/baseline-management

Commands to perform a dry run or production deployment of custom DocTypes using the setup script. Requires an environment file for configuration.

```bash
# Dry run to verify
python frappe_setup_custom_doctypes.py --dry-run --env ../../.env.example

# Create on target instance
python frappe_setup_custom_doctypes.py --env ../../.env.example
```

--------------------------------

### Extract and Configure CTMS Bundle (Shell)

Source: https://docs.zynomi.com/deployment/bundle-deployment

Extracts the downloaded CTMS bundle archive and navigates into the extracted directory. It then copies an example configuration file and prompts the user to edit it with server IP and Docker Hub credentials.

```shell
tar xzf zynctl-bundle-<version>.tar.gz  
cd zynctl-bundle-<version>  

# Create config  
cp zynctl.conf.example zynctl.conf  
```

```shell
# ── Required ──────────────────────────────────  
SERVER_HOST=<your-server-ip>  

# ── Docker Hub (required to avoid rate limits) ─  
DOCKER_USERNAME=<your-dockerhub-username>  
DOCKER_PASSWORD=<your-dockerhub-password>  
```

--------------------------------

### Install Tar Package (Shell)

Source: https://docs.zynomi.com/deployment/bundle-deployment

Installs the 'tar' package on RHEL-family Linux distributions using the dnf package manager. This is a prerequisite for extracting the downloaded CTMS bundle. Requires root or sudo privileges.

```shell
sudo dnf install -y tar  
```

--------------------------------

### Install sshpass on Different Systems

Source: https://docs.zynomi.com/deployment/single-click-deployment

Provides commands to install the `sshpass` utility, which is required for password-based SSH authentication on macOS, Ubuntu/Debian, and RHEL-based systems.

```bash
# macOS
brew install hudochenkov/sshpass/sshpass

# Ubuntu/Debian
sudo apt-get install sshpass

# RHEL/Rocky/Amazon Linux
sudo dnf install sshpass
```

--------------------------------

### GET /healthz

Source: https://docs.zynomi.com/deployment/single-click-deployment

Checks the health status of the OpenObserve logging service.

```APIDOC
## GET /healthz

### Description
Verifies that the OpenObserve service is operational.

### Method
GET

### Endpoint
http://localhost:5080/healthz

### Response
#### Success Response (200)
- **status** (string) - The health status of the service.

#### Response Example
{
  "status": "ok"
}
```

--------------------------------

### Deploy Zynctl Bundle to Server

Source: https://docs.zynomi.com/recipes/hetzner-vm

Transfers the deployment bundle to the remote server, extracts it, and executes the full deployment script.

```bash
scp -i ~/.ssh/ctms-hetzner zynctl-bundle-*.tar.gz root@<ip>:~
ssh -i ~/.ssh/ctms-hetzner root@<ip>
tar xzf zynctl-bundle-*.tar.gz && cd zynctl-bundle-*
cp zynctl.conf.example zynctl.conf
# Edit zynctl.conf: set SERVER_HOST=<ip> and Docker Hub creds
./zynctl.sh full-deploy
```

--------------------------------

### GET /api/health

Source: https://docs.zynomi.com/deployment/single-click-deployment

Checks the health status of the Zynexa CTMS application.

```APIDOC
## GET /api/health

### Description
Verifies that the Zynexa CTMS application is running and responsive.

### Method
GET

### Endpoint
http://localhost:3000/api/health

### Response
#### Success Response (200)
- **status** (string) - The health status of the service.

#### Response Example
{
  "status": "ok"
}
```

--------------------------------

### GET /__health

Source: https://docs.zynomi.com/deployment/single-click-deployment

Checks the health status of the KrakenD API Gateway.

```APIDOC
## GET /__health

### Description
Verifies that the KrakenD API Gateway is operational.

### Method
GET

### Endpoint
http://localhost:9080/__health

### Response
#### Success Response (200)
- **status** (string) - The health status of the service.

#### Response Example
{
  "status": "ok"
}
```

--------------------------------

### Define Custom DocType in Setup Script

Source: https://docs.zynomi.com/deployment/baseline-management

Demonstrates the structure for appending a new custom DocType definition to the provisioning list in frappe_setup_custom_doctypes.py. Includes metadata such as naming rules and field configurations.

```python
PHASE_1.append({
    "name": "Your DocType",
    "module": "Healthcare",
    "custom": 1,
    "naming_rule": "By fieldname",
    "autoname": "field:your_field",
    "fields": [
        {"fieldname": "your_field", "fieldtype": "Data", "label": "Your Field", "reqd": 1},
    ],
})
```

--------------------------------

### Start Frappe Stack

Source: https://docs.zynomi.com/deployment/docker-deployment-guide

Initiates the Frappe stack services in detached mode using Docker Compose. This should be started after Supabase, as Frappe serves as the clinical data backend required by CTMS applications.

```bash
cd frappe-marley-health && docker compose up -d
```

--------------------------------

### Start Supabase Stack

Source: https://docs.zynomi.com/deployment/docker-deployment-guide

Initiates the Supabase stack services in detached mode using Docker Compose. This is the recommended first step for starting the CTMS environment as Supabase provides authentication services.

```bash
cd supabase && docker compose up -d
```

--------------------------------

### Start Database and Wait for Healthy

Source: https://docs.zynomi.com/deployment/docker-deployment-guide

Starts the lakehouse database service in detached mode using Docker Compose with production environment variables. This command ensures the database is running before subsequent operations.

```bash
docker compose --env-file .env.production --profile lakehouse up -d lakehouse-db
```

--------------------------------

### Execute Custom DocType Provisioning

Source: https://docs.zynomi.com/deployment/initial-setup-and-configuration

Commands to run the Python script responsible for creating the 34 custom DocTypes in the required dependency order.

```bash
cd ctms.devops/scripts/frappe-seed
source venv/bin/activate

# Preview (dry run)
python frappe_setup_custom_doctypes.py --dry-run --env ../../.env.example

# Create ALL 34 custom DocTypes
python frappe_setup_custom_doctypes.py --env ../../.env.example
```

--------------------------------

### Download CTMS Install Bundle (Shell)

Source: https://docs.zynomi.com/deployment/bundle-deployment

Downloads the CTMS platform's install bundle using a provided presigned URL. The curl command with the -LO flag saves the file with its original name. Ensure you use the complete URL provided by your Zynomi account representative.

```shell
# Paste the complete download URL provided by your account representative  
curl -LO '<YOUR_DOWNLOAD_URL>'
```

--------------------------------

### Cube.js Query Client Example - TypeScript

Source: https://docs.zynomi.com/architecture/dashboard-development

Provides an example of the Cube.js query client in TypeScript, specifically defining the `enrollmentMetrics` query. This client is used to construct and send queries to the Cube.js API.

```typescript
export const ClinicalQueries = {  
  enrollmentMetrics: (dateRange?: [string, string]): CubeQuery => ({  
    measures: [  
      "Enrollments.subjectCount",  
      "Enrollments.screenFailureCount",  
    ],  
    timeDimensions: dateRange ? [{  
      dimension: "Enrollments.enrollmentDate",  
      dateRange,  
    }] : undefined,  
  }),  
  // ... more queries  
};  

```

--------------------------------

### Automate CTMS Provisioning with Docker

Source: https://docs.zynomi.com/deployment/initial-setup-and-configuration

Commands to trigger the automated ctms-init container for full provisioning or selective stage execution. Supports environment configuration and dry-run modes for safe testing.

```bash
# Run all 5 stages
docker compose --env-file .env.production --profile init up ctms-init

# Run only stages 3 and 4
CTMS_INIT_STAGES=3,4 docker compose --env-file .env.production run --rm ctms-init

# Run only Stage 5 (default practitioner)
CTMS_INIT_STAGES=5 docker compose --env-file .env.production run --rm ctms-init

# Preview without making changes
CTMS_INIT_DRY_RUN=true docker compose --env-file .env.production run --rm ctms-init
```

--------------------------------

### KPICard Widget Example - JSX

Source: https://docs.zynomi.com/architecture/dashboard-development

Shows an example of using the `KPICard` reusable widget component. This component is used to display a single key performance indicator with a title, value, subtitle, icon, and loading state.

```jsx
<KPICard  
  title="Total Enrolled"  
  value={formatCompactNumber(enrolled)}  
  subtitle="Subjects in studies"  
  icon={Users}  
  isLoading={isLoading}  
/>  

```

--------------------------------

### Troubleshoot Supabase Initialization

Source: https://docs.zynomi.com/deployment/single-click-deployment

Commands to inspect logs and verify the status of Supabase services if they fail to initialize correctly.

```bash
./install.sh ssh
cd /opt/ctms-deployment/supabase
docker compose ps
docker compose logs analytics
```

--------------------------------

### Docker Compose Startup Order for Self-Hosted CTMS

Source: https://docs.zynomi.com/deployment/docker-compose-profiles

Details the sequential commands required to start the full self-hosted CTMS stack, including Supabase, Frappe, and CTMS services. This order ensures dependencies are met before starting application services.

```bash
cd supabase && docker compose up -d

cd frappe-marley-health && docker compose up -d

docker compose --profile init run --rm ctms-supabase-seed

docker compose --profile init up ctms-init

docker compose --profile init up ctms-user-seed

docker compose -f ... --profile all up -d
```

--------------------------------

### Generate SQL from Query Definitions

Source: https://docs.zynomi.com/architecture/mcp/preview-sql

These examples demonstrate how to construct JSON input objects to generate SQL for simple counts, grouped queries, filtered datasets, and time-series analysis.

```json
{
  "measures": ["Studies.count"]
}
```

```json
{
  "measures": ["Enrollments.count"],
  "dimensions": ["Sites.siteName"]
}
```

```json
{
  "measures": ["Studies.count"],
  "dimensions": ["Studies.studyName"],
  "filters": [
    {
      "member": "Studies.phase",
      "operator": "equals",
      "values": ["Phase 3"]
    }
  ]
}
```

```json
{
  "measures": ["Enrollments.count"],
  "timeDimensions": [
    {
      "dimension": "Enrollments.enrollmentDate",
      "granularity": "month",
      "dateRange": ["2024-01-01", "2024-12-31"]
    }
  ]
}
```

--------------------------------

### Full Deployment of CTMS Platform (Shell)

Source: https://docs.zynomi.com/deployment/bundle-deployment

Initiates the complete deployment of the CTMS platform using the zynctl.sh script. Requires setting the SERVER_HOST environment variable to your server's IP address. This command handles all necessary installations and configurations.

```shell
SERVER_HOST=<your-ip> ./zynctl.sh full-deploy  
```

--------------------------------

### Troubleshooting and Resource Management

Source: https://docs.zynomi.com/deployment/aws-ec2-deployment

Commands for debugging container crashes and optimizing resource usage by starting services based on profiles.

```bash
docker compose logs zynexa
docker compose restart zynexa
docker compose --profile core up -d
```

--------------------------------

### Production Deployment via zynctl

Source: https://docs.zynomi.com/deployment/docker-compose-profiles

Executes a full production deployment on a Linux VM using the zynctl bundle script, which automates the startup sequence for the entire stack.

```bash
SERVER_HOST=<your-ip> ./zynctl.sh full-deploy
```

--------------------------------

### Start Docker Compose with Production Overrides

Source: https://docs.zynomi.com/deployment/docker-deployment-guide

Command to start Docker Compose services using production-specific overrides. It includes the main compose file, a production override file, the environment file, and selects the analytics and lakehouse profiles. This configuration is suitable for EC2 or IP-based access scenarios.

```bash
docker compose -f docker-compose.yml -f docker-compose.prod.yml \
  --env-file .env.production --profile analytics --profile lakehouse up -d

```

--------------------------------

### Deploy CTMS via Environment Variables

Source: https://docs.zynomi.com/deployment/single-click-deployment

Shows how to pass configuration settings as environment variables directly on the command line, offering flexibility for different authentication methods and modes.

```bash
# Key-based SSH
SERVER_HOST=203.0.113.50 ./install.sh deploy

# Password-based SSH
SERVER_HOST=203.0.113.50 SSH_PASSWORD=mypassword ./install.sh deploy

# Local mode (on the server itself)
LOCAL_MODE=true ./install.sh deploy
```

--------------------------------

### Configure Frappe Environment

Source: https://docs.zynomi.com/deployment/self-hosted-vendor-stacks

Sets up the Frappe environment by copying a sample .env file and highlighting key variables to configure for Frappe.

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

```

--------------------------------

### Manage Hetzner Infrastructure with hcloud CLI

Source: https://docs.zynomi.com/recipes/hetzner-vm

Automates server lifecycle management including installation, authentication, creation, and snapshotting using the Hetzner Cloud CLI.

```bash
# Install (macOS)
brew install hcloud

# Authenticate
hcloud context create ctms

# Create CX43 VM
hcloud server create \
  --name ctms-prod-1 \
  --type cx43 \
  --image rocky-10 \
  --ssh-key ctms-key

# Get IP
hcloud server ip ctms-prod-1

# Snapshot before risky changes
hcloud server create-image --type snapshot --description "pre-deploy" ctms-prod-1

# Delete
hcloud server delete ctms-prod-1
```