ContextDX Installation Guide

Welcome to ContextDX! This guide will help you install and configure ContextDX on your own infrastructure.

---

Table of Contents

1. System Requirements
2. Quick Start
3. Configuration
4. Starting the Platform
5. Accessing the Application
6. Verifying Installation
7. Upgrades
8. Stopping and Restarting
9. Getting Help

Related Guides:

• Troubleshooting Guide
• Backup & Restore Guide
• SSL & Reverse Proxy Guide

---

System Requirements

Minimum Requirements

Software Requirements

Network Requirements

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:

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

Windows (PowerShell):

POWERSHELLCopy
# No preflight script for Windows yet - check requirements manually

This checks Docker, memory, disk space, ports, and network connectivity.

Step 1: Download the Installation Files

Option A: One-line installer (Recommended)

Linux/macOS:

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

Windows (PowerShell):

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

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

Option B: Manual download

BASHCopy
# Create installation directory
mkdir contextdx && cd contextdx

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

Or copy from the provided package:

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

Step 2: Configure Environment

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

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

Step 3: Start the Platform

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

Step 4: Access the Application

Open your browser and navigate to:

http://localhost

Or if you configured a different port:

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:

1. Log in to Portal
2. Navigate to Dashboard → Deployments
3. Select your deployment
4. Copy the Deployment ID and Deployment Secret

BASHCopy
# .env file
CDX_DEPLOYMENT_ID=your-deployment-id-here
CDX_DEPLOYMENT_SECRET=your-deployment-secret-here

Database Password

Set a strong, unique password for the database:

BASHCopy
# .env file
CDX_DATABASE_PASSWORD=YourSecurePassword123!

Security Note: 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:

BASHCopy
# .env file
CDX_PORT=8080

Specify a Version

Pin to a specific version instead of latest:

BASHCopy
# .env file
CDX_VERSION=1.2.3

AI Features (Optional)

If you want to use AI-powered features, add your API keys:

BASHCopy
# .env file
OPENAI_API_KEY=sk-your-openai-key
ANTHROPIC_API_KEY=sk-ant-your-anthropic-key

Database Tuning (Optional)

For high-load environments:

BASHCopy
# .env file
CDX_DATABASE_MAX_CONNECTIONS=20
CDX_DATABASE_IDLE_TIMEOUT=60000

Complete Configuration Example

BASHCopy
# ===========================================
# Required
# ===========================================
CDX_DEPLOYMENT_ID=dep_abc123xyz
CDX_DEPLOYMENT_SECRET=secret_xyz789abc
CDX_DATABASE_PASSWORD=MySecureP@ssw0rd!

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

# AI Features (optional)
# OPENAI_API_KEY=sk-...
# ANTHROPIC_API_KEY=sk-ant-...

---

Starting the Platform

First Time Start

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

This will:

1. Download the Docker images (first time only)
2. Create the database
3. Start all services
4. Run database migrations

View Startup Progress

BASHCopy
# 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

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

Expected output:

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

First Login

1. Click Sign In
2. You'll be redirected to Portal for authentication
3. Log in with your Portal credentials
4. You'll be redirected back to ContextDX

---

Verifying Installation

Automated Verification (Recommended)

Use the verification script to check all components:

Linux/macOS:

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

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

Windows (PowerShell):

POWERSHELLCopy
# 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

ContextDX provides multiple health check endpoints:

BASHCopy
# 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:

JSONCopy
{"status":"ok"}

Detailed Status

BASHCopy
curl http://localhost/api/status

This returns detailed information about:

• Database connectivity
• Portal connectivity
• File system access
• Platform version

Service Health

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

---

Upgrades

Check Current Version

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

Upgrade to Latest

BASHCopy
# 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

BASHCopy
# 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:

BASHCopy
# 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

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

Note: This stops containers but preserves data.

Restart All Services

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

Restart Single Service

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

Complete Reset (Caution!)

Warning: This deletes ALL data including the database!

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

---

Getting Help

Logs for Support

When contacting support, include:

BASHCopy
# 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

Usage:

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

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

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

Useful Commands Reference

---

Thank you for choosing ContextDX!