Installation Guide

This guide takes you from nothing to a running self-hosted deployment on Docker Compose.

Related guides:

System requirements

Minimum requirements

Resource	Requirement
CPU	2 cores
RAM	4 GB
Disk	20 GB free space
OS	Linux (Ubuntu 20.04+, CentOS 8+), Windows Server 2019+, macOS

Software requirements

Software	Version	Notes
Docker	20.10+	Install Docker
Docker Compose	v2+	Usually included with Docker Desktop

Network requirements

Port	Protocol	Purpose
80	TCP	Web interface (configurable)
443	TCP	HTTPS (if using SSL termination)

The platform needs outbound internet access to:

portal.contextdx.com (or your configured Portal URL)
registry.hub.docker.com (to pull images)

Quick start

Step 0: pre-flight check (recommended)

Before installing, verify your system meets all requirements:

Linux/macOS:

BASH

curl -fsSL https://raw.githubusercontent.com/syntaxia/contextdx/main/deploy/preflight.sh | bash

This checks Docker, memory, disk space, ports, and network connectivity. There's no pre-flight script for Windows yet — check the requirements above by hand.

Step 1: download the installation files

Option A: One-line installer (Recommended)

Linux/macOS:

BASH

curl -fsSL https://raw.githubusercontent.com/syntaxia/contextdx/main/deploy/install.sh | bash

Windows (PowerShell):

POWERSHELL

iwr -useb https://raw.githubusercontent.com/syntaxia/contextdx/main/deploy/install.ps1 | iex

This downloads all required files to ~/contextdx (or %USERPROFILE%\contextdx on Windows).

Option B: Manual download

BASH

# Create installation directory
mkdir contextdx && cd contextdx

# Download required files
curl -O https://raw.githubusercontent.com/syntaxia/contextdx/main/deploy/docker-compose.production.yml
curl -O https://raw.githubusercontent.com/syntaxia/contextdx/main/deploy/nginx.conf
curl -O https://raw.githubusercontent.com/syntaxia/contextdx/main/deploy/.env.template

Or copy from the provided package:

BASH

cp -r /path/to/deploy/* ./

Step 2: configure environment

BASH

# Create your configuration file
cp .env.template .env

# Edit with your credentials
nano .env  # or use your preferred editor

Step 3: start the platform

BASH

docker compose -f docker-compose.production.yml up -d

Step 4: access the application

Open your browser and navigate to:

CODE

http://localhost

Or if you configured a different port:

CODE

http://localhost:YOUR_PORT

Configuration

Required configuration

Edit your .env file and set these required values:

Portal Credentials

Get these from your Portal dashboard at https://portal.contextdx.com:

Log in to Portal
Navigate to Dashboard → Deployments
Select your deployment
Copy the Deployment ID and Deployment Secret

BASH

# .env file
CDX_APP_ID=your-deployment-id-here
CDX_APP_SECRET=your-deployment-secret-here

Database Password

Set a strong, unique password for the database:

BASH

# .env file
CDX_DATABASE_PASSWORD=YourSecurePassword123!

Important

Use a strong password with letters, numbers, and special characters. This password is stored locally and never transmitted to Portal.

Optional configuration

Change the External Port

If port 80 is already in use:

BASH

# .env file
CDX_PORT=8080

Specify a Version

Pin to a specific version instead of latest:

BASH

# .env file
CDX_VERSION=1.2.3

AI features (optional)

Chat and in-app insight generation run through a model provider, which your admins connect once from Settings → Integrations inside the app — same as on cloud. See the Integrations Reference.

One env var is deployment-level rather than per-org: OPENROUTER_PLATFORM_KEY funds the trial credits new organizations get before they connect their own provider. Leave it empty and trial turns are simply off.

BASH

# .env file — optional
OPENROUTER_PLATFORM_KEY=sk-or-your-platform-key

Warning

This key is billed to you, not to your users' orgs. If you set it, set a spend cap on the OpenRouter account behind it.

The plugin loop — /analyze, /sync, /insights — needs no model provider at all; it runs inside your developers' own coding sessions.

Database Tuning (Optional)

For high-load environments:

BASH

# .env file
CDX_DATABASE_MAX_CONNECTIONS=20
CDX_DATABASE_IDLE_TIMEOUT=60000

Complete configuration example

BASH

# ===========================================
# Required
# ===========================================
CDX_APP_ID=dep_abc123xyz
CDX_APP_SECRET=secret_xyz789abc
CDX_DATABASE_PASSWORD=MySecureP@ssw0rd!

# ===========================================
# Optional
# ===========================================
# CDX_PORT=80
# CDX_VERSION=latest
# CDX_PORTAL_URL=https://portal.contextdx.com

# Trial credits for new orgs (optional)
# OPENROUTER_PLATFORM_KEY=sk-or-...

Starting the platform

First time start

BASH

# Pull the latest images and start
docker compose -f docker-compose.production.yml up -d

This will:

Download the Docker images (first time only)
Create the database
Start all services
Run database migrations

View startup progress

BASH

# Watch all logs
docker compose -f docker-compose.production.yml logs -f

# Watch specific service
docker compose -f docker-compose.production.yml logs -f server

Check service status

BASH

docker compose -f docker-compose.production.yml ps

Expected output:

CODE

NAME                  STATUS                   PORTS
contextdx-proxy       Up (healthy)            0.0.0.0:80->80/tcp
contextdx-web         Up (healthy)
contextdx-server      Up (healthy)
contextdx-postgres    Up (healthy)

All services should show Up (healthy).

Accessing the application

Web interface

Open your browser and go to:

Default: http://localhost
Custom port: http://localhost:YOUR_PORT
Custom domain: http://your-domain.com

Click Sign In
You'll be redirected to Portal for authentication
Log in with your Portal credentials
You'll be redirected back to the platform

Verifying installation

Automated verification (recommended)

Use the verification script to check all components:

Linux/macOS:

BASH

# Download and run verification script
curl -fsSL https://raw.githubusercontent.com/syntaxia/contextdx/main/deploy/verify.sh | bash

# Or if you have the script locally
./verify.sh

Windows (PowerShell):

POWERSHELL

# Download and run verification script
.\verify.ps1

The verification script checks:

Docker daemon status
All containers running and healthy
API health endpoint
Platform status
Web UI accessibility
Database connectivity
Portal connectivity
Data volumes

Manual health checks

You can hit several health check endpoints:

Endpoint	Service	Purpose
`/nginx-health`	nginx	Proxy health
`/health`	server	Backend health
`/api/health`	web	Frontend health

BASH

# Check backend server health
curl http://localhost/health

# Check frontend health
curl http://localhost/api/health

# Check nginx proxy health
curl http://localhost/nginx-health

Expected response for /health:

JSON

{"status":"ok"}

Detailed status

BASH

curl http://localhost/api/status

This returns detailed information about:

Database connectivity
Portal connectivity
File system access
Platform version

Service health

BASH

# All services should be healthy
docker compose -f docker-compose.production.yml ps

Upgrades

Check current version

BASH

docker compose -f docker-compose.production.yml images

Upgrade to latest

BASH

# Pull new images
docker compose -f docker-compose.production.yml pull

# Restart with new images
docker compose -f docker-compose.production.yml up -d

Upgrade to specific version

BASH

# Edit .env
CDX_VERSION=1.3.0

# Apply upgrade
docker compose -f docker-compose.production.yml pull
docker compose -f docker-compose.production.yml up -d

Rollback

If something goes wrong:

BASH

# Edit .env to previous version
CDX_VERSION=1.2.0

# Rollback
docker compose -f docker-compose.production.yml up -d

Stopping and restarting

Stop all services

BASH

docker compose -f docker-compose.production.yml down

Note

This stops containers but preserves data.

Restart all services

BASH

docker compose -f docker-compose.production.yml restart

Restart single service

BASH

docker compose -f docker-compose.production.yml restart server

Complete reset (caution!)

Caution

This deletes ALL data including the database!

BASH

docker compose -f docker-compose.production.yml down -v

Getting help

Logs for support

When contacting support, include:

BASH

# Save logs to file
docker compose -f docker-compose.production.yml logs > contextdx-logs.txt 2>&1

# Include service status
docker compose -f docker-compose.production.yml ps >> contextdx-logs.txt

# Include configuration (without secrets!)
grep -v SECRET .env | grep -v PASSWORD >> contextdx-logs.txt

Support channels

Documentation: https://docs.contextdx.com
Portal Dashboard: https://portal.contextdx.com
Email Support: support@contextdx.com

Helper scripts reference

Script	Platform	Purpose
`preflight.sh`	Linux/macOS	Check system requirements before installation
`install.sh`	Linux/macOS	Download and set up all required files
`install.ps1`	Windows	Download and set up all required files
`verify.sh`	Linux/macOS	Verify deployment is working correctly
`verify.ps1`	Windows	Verify deployment is working correctly

Usage:

BASH

# Pre-flight check (before install)
curl -fsSL https://raw.githubusercontent.com/syntaxia/contextdx/main/deploy/preflight.sh | bash

# Install (downloads files to ~/contextdx)
curl -fsSL https://raw.githubusercontent.com/syntaxia/contextdx/main/deploy/install.sh | bash

# Verify (after starting containers)
./verify.sh

Useful commands reference

Command	Purpose
`docker compose -f docker-compose.production.yml up -d`	Start all services
`docker compose -f docker-compose.production.yml down`	Stop all services
`docker compose -f docker-compose.production.yml ps`	Check status
`docker compose -f docker-compose.production.yml logs`	View logs
`docker compose -f docker-compose.production.yml logs -f server`	Follow server logs
`docker compose -f docker-compose.production.yml pull`	Pull latest images
`docker compose -f docker-compose.production.yml restart`	Restart all
`docker compose -f docker-compose.production.yml exec server sh`	Shell into server

Installation Guide

This guide takes you from nothing to a running self-hosted deployment on Docker Compose.

Related guides:

System requirements

Minimum requirements

Resource	Requirement
CPU	2 cores
RAM	4 GB
Disk	20 GB free space
OS	Linux (Ubuntu 20.04+, CentOS 8+), Windows Server 2019+, macOS

Software requirements

Software	Version	Notes
Docker	20.10+	Install Docker
Docker Compose	v2+	Usually included with Docker Desktop

Network requirements

Port	Protocol	Purpose
80	TCP	Web interface (configurable)
443	TCP	HTTPS (if using SSL termination)

The platform needs outbound internet access to:

portal.contextdx.com (or your configured Portal URL)
registry.hub.docker.com (to pull images)

Quick start

Step 0: pre-flight check (recommended)

Before installing, verify your system meets all requirements:

Linux/macOS:

BASH

curl -fsSL https://raw.githubusercontent.com/syntaxia/contextdx/main/deploy/preflight.sh | bash

This checks Docker, memory, disk space, ports, and network connectivity. There's no pre-flight script for Windows yet — check the requirements above by hand.

Step 1: download the installation files

Option A: One-line installer (Recommended)

Linux/macOS:

BASH

curl -fsSL https://raw.githubusercontent.com/syntaxia/contextdx/main/deploy/install.sh | bash

Windows (PowerShell):

POWERSHELL

iwr -useb https://raw.githubusercontent.com/syntaxia/contextdx/main/deploy/install.ps1 | iex

This downloads all required files to ~/contextdx (or %USERPROFILE%\contextdx on Windows).

Option B: Manual download

BASH

# Create installation directory
mkdir contextdx && cd contextdx

# Download required files
curl -O https://raw.githubusercontent.com/syntaxia/contextdx/main/deploy/docker-compose.production.yml
curl -O https://raw.githubusercontent.com/syntaxia/contextdx/main/deploy/nginx.conf
curl -O https://raw.githubusercontent.com/syntaxia/contextdx/main/deploy/.env.template

Or copy from the provided package:

BASH

cp -r /path/to/deploy/* ./

Step 2: configure environment

BASH

# Create your configuration file
cp .env.template .env

# Edit with your credentials
nano .env  # or use your preferred editor

Step 3: start the platform

BASH

docker compose -f docker-compose.production.yml up -d

Step 4: access the application

Open your browser and navigate to:

CODE

http://localhost

Or if you configured a different port:

CODE

http://localhost:YOUR_PORT

Configuration

Required configuration

Edit your .env file and set these required values:

Portal Credentials

Get these from your Portal dashboard at https://portal.contextdx.com:

Log in to Portal
Navigate to Dashboard → Deployments
Select your deployment
Copy the Deployment ID and Deployment Secret

BASH

# .env file
CDX_APP_ID=your-deployment-id-here
CDX_APP_SECRET=your-deployment-secret-here

Database Password

Set a strong, unique password for the database:

BASH

# .env file
CDX_DATABASE_PASSWORD=YourSecurePassword123!

Important

Use a strong password with letters, numbers, and special characters. This password is stored locally and never transmitted to Portal.

Optional configuration

Change the External Port

If port 80 is already in use:

BASH

# .env file
CDX_PORT=8080

Specify a Version

Pin to a specific version instead of latest:

BASH

# .env file
CDX_VERSION=1.2.3

AI features (optional)

BASH

# .env file — optional
OPENROUTER_PLATFORM_KEY=sk-or-your-platform-key

Warning

This key is billed to you, not to your users' orgs. If you set it, set a spend cap on the OpenRouter account behind it.

The plugin loop — /analyze, /sync, /insights — needs no model provider at all; it runs inside your developers' own coding sessions.

Database Tuning (Optional)

For high-load environments:

BASH

# .env file
CDX_DATABASE_MAX_CONNECTIONS=20
CDX_DATABASE_IDLE_TIMEOUT=60000

Complete configuration example

BASH

# ===========================================
# Required
# ===========================================
CDX_APP_ID=dep_abc123xyz
CDX_APP_SECRET=secret_xyz789abc
CDX_DATABASE_PASSWORD=MySecureP@ssw0rd!

# ===========================================
# Optional
# ===========================================
# CDX_PORT=80
# CDX_VERSION=latest
# CDX_PORTAL_URL=https://portal.contextdx.com

# Trial credits for new orgs (optional)
# OPENROUTER_PLATFORM_KEY=sk-or-...

Starting the platform

First time start

BASH

# Pull the latest images and start
docker compose -f docker-compose.production.yml up -d

This will:

Download the Docker images (first time only)
Create the database
Start all services
Run database migrations

View startup progress

BASH

# Watch all logs
docker compose -f docker-compose.production.yml logs -f

# Watch specific service
docker compose -f docker-compose.production.yml logs -f server

Check service status

BASH

docker compose -f docker-compose.production.yml ps

Expected output:

CODE

NAME                  STATUS                   PORTS
contextdx-proxy       Up (healthy)            0.0.0.0:80->80/tcp
contextdx-web         Up (healthy)
contextdx-server      Up (healthy)
contextdx-postgres    Up (healthy)

All services should show Up (healthy).

Accessing the application

Web interface

Open your browser and go to:

Default: http://localhost
Custom port: http://localhost:YOUR_PORT
Custom domain: http://your-domain.com

Click Sign In
You'll be redirected to Portal for authentication
Log in with your Portal credentials
You'll be redirected back to the platform

Verifying installation

Automated verification (recommended)

Use the verification script to check all components:

Linux/macOS:

BASH

# Download and run verification script
curl -fsSL https://raw.githubusercontent.com/syntaxia/contextdx/main/deploy/verify.sh | bash

# Or if you have the script locally
./verify.sh

Windows (PowerShell):

POWERSHELL

# Download and run verification script
.\verify.ps1

The verification script checks:

Docker daemon status
All containers running and healthy
API health endpoint
Platform status
Web UI accessibility
Database connectivity
Portal connectivity
Data volumes

Manual health checks

You can hit several health check endpoints:

Endpoint	Service	Purpose
`/nginx-health`	nginx	Proxy health
`/health`	server	Backend health
`/api/health`	web	Frontend health

BASH

# Check backend server health
curl http://localhost/health

# Check frontend health
curl http://localhost/api/health

# Check nginx proxy health
curl http://localhost/nginx-health

Expected response for /health:

JSON

{"status":"ok"}

Detailed status

BASH

curl http://localhost/api/status

This returns detailed information about:

Database connectivity
Portal connectivity
File system access
Platform version

Service health

BASH

# All services should be healthy
docker compose -f docker-compose.production.yml ps

Upgrades

Check current version

BASH

docker compose -f docker-compose.production.yml images

Upgrade to latest

BASH

# Pull new images
docker compose -f docker-compose.production.yml pull

# Restart with new images
docker compose -f docker-compose.production.yml up -d

Upgrade to specific version

BASH

# Edit .env
CDX_VERSION=1.3.0

# Apply upgrade
docker compose -f docker-compose.production.yml pull
docker compose -f docker-compose.production.yml up -d

Rollback

If something goes wrong:

BASH

# Edit .env to previous version
CDX_VERSION=1.2.0

# Rollback
docker compose -f docker-compose.production.yml up -d

Stopping and restarting

Stop all services

BASH

docker compose -f docker-compose.production.yml down

Note

This stops containers but preserves data.

Restart all services

BASH

docker compose -f docker-compose.production.yml restart

Restart single service

BASH

docker compose -f docker-compose.production.yml restart server

Complete reset (caution!)

Caution

This deletes ALL data including the database!

BASH

docker compose -f docker-compose.production.yml down -v

Getting help

Logs for support

When contacting support, include:

BASH

# Save logs to file
docker compose -f docker-compose.production.yml logs > contextdx-logs.txt 2>&1

# Include service status
docker compose -f docker-compose.production.yml ps >> contextdx-logs.txt

# Include configuration (without secrets!)
grep -v SECRET .env | grep -v PASSWORD >> contextdx-logs.txt

Support channels

Documentation: https://docs.contextdx.com
Portal Dashboard: https://portal.contextdx.com
Email Support: support@contextdx.com

Helper scripts reference

Script	Platform	Purpose
`preflight.sh`	Linux/macOS	Check system requirements before installation
`install.sh`	Linux/macOS	Download and set up all required files
`install.ps1`	Windows	Download and set up all required files
`verify.sh`	Linux/macOS	Verify deployment is working correctly
`verify.ps1`	Windows	Verify deployment is working correctly

Usage:

BASH

# Pre-flight check (before install)
curl -fsSL https://raw.githubusercontent.com/syntaxia/contextdx/main/deploy/preflight.sh | bash

# Install (downloads files to ~/contextdx)
curl -fsSL https://raw.githubusercontent.com/syntaxia/contextdx/main/deploy/install.sh | bash

# Verify (after starting containers)
./verify.sh

Useful commands reference

Command	Purpose
`docker compose -f docker-compose.production.yml up -d`	Start all services
`docker compose -f docker-compose.production.yml down`	Stop all services
`docker compose -f docker-compose.production.yml ps`	Check status
`docker compose -f docker-compose.production.yml logs`	View logs
`docker compose -f docker-compose.production.yml logs -f server`	Follow server logs
`docker compose -f docker-compose.production.yml pull`	Pull latest images
`docker compose -f docker-compose.production.yml restart`	Restart all
`docker compose -f docker-compose.production.yml exec server sh`	Shell into server

Installation Guide

System requirements

Minimum requirements

Software requirements

Network requirements

Quick start

Step 0: pre-flight check (recommended)

Step 1: download the installation files

Step 2: configure environment

Step 3: start the platform

Step 4: access the application

Configuration

Required configuration

Optional configuration

Complete configuration example

Starting the platform

First time start

View startup progress

Check service status

Accessing the application

Web interface

First login

Verifying installation

Automated verification (recommended)

Manual health checks

Detailed status

Service health

Upgrades

Check current version

Upgrade to latest

Upgrade to specific version

Rollback

Stopping and restarting

Stop all services

Restart all services

Restart single service

Complete reset (caution!)

Getting help

Logs for support

Support channels

Helper scripts reference

Useful commands reference

Installation Guide

System requirements

Minimum requirements

Software requirements

Network requirements

Quick start

Step 0: pre-flight check (recommended)

Step 1: download the installation files

Step 2: configure environment

Step 3: start the platform

Step 4: access the application

Configuration

Required configuration

Optional configuration

Complete configuration example

Starting the platform

First time start

View startup progress

Check service status

Accessing the application

Web interface

First login

Verifying installation

Automated verification (recommended)

Manual health checks

Detailed status

Service health

Upgrades

Check current version

Upgrade to latest

Upgrade to specific version

Rollback

Stopping and restarting

Stop all services

Restart all services

Restart single service

Complete reset (caution!)

Getting help