Deploying Conductor¶

How to build and deploy the docs site and MCP service to konstant-server.

What gets deployed¶

Component	URL	Location on server
Docs site (MkDocs)	`https://conductor-docs.hectorsanchez.eu`	`/srv/apps/conductor-docs/current/`
MCP service (FastAPI)	`https://conductor-konstant.hectorsanchez.eu`	`/srv/apps/conductor/current/`

The docs site is static HTML served by nginx. The MCP service is a socket-activated uvicorn process behind nginx.

Prerequisites¶

SSH access to konstant-server as sdhector (has passwordless sudo)
Repo cloned on the server at /srv/apps/conductor/shared/repo
Python venv at /srv/apps/conductor/shared/venv

Deploying the docs site¶

Build locally¶

cd conductor/
pip install -r requirements-docs.txt
mkdocs build --strict

This produces site/ — static HTML. Verify locally:

mkdocs serve   # http://127.0.0.1:8000

Deploy to konstant¶

The site/ directory must be copied to the server. From Windows, build locally then upload:

# Build MkDocs locally first
mkdocs build --strict

# Upload site/ to temporary location on server
scp -r site/* konstant:/tmp/docs-site/

# Create a new release and activate it
ssh konstant "bash -c '
  APP=/srv/apps/conductor-docs
  REL=\$(date -u +%Y%m%dT%H%M%SZ)
  mkdir -p \$APP/releases/\$REL
  rsync -a /tmp/docs-site/ \$APP/releases/\$REL/
  ln -sfn \$APP/releases/\$REL \$APP/current
  echo \"Docs release: \$REL\"
'"

The docs site is now live — nginx serves directly from the current symlink. No service restart needed.

Deploying the MCP service¶

Write a deploy script¶

Create a bash script with the deployment steps. Example pattern:

#!/usr/bin/env bash
set -e
REPO=/srv/apps/conductor/shared/repo
APP=/srv/apps/conductor
REL=$(date -u +%Y%m%dT%H%M%SZ)

# Pull latest code
sudo -u deploy git -C $REPO pull origin main

# Stage new release
sudo -u deploy mkdir -p $APP/releases/$REL
sudo -u deploy rsync -a \
  --exclude .git --exclude .venv --exclude venv --exclude shared \
  --exclude __pycache__ --exclude '*.pyc' --exclude .env \
  --exclude archive \
  $REPO/ $APP/releases/$REL/

# Install dependencies
$APP/shared/venv/bin/pip install -q -r $APP/releases/$REL/requirements.txt

# Activate release
sudo -u deploy ln -sfn $APP/releases/$REL $APP/current

# Restart service
sudo systemctl stop conductor.socket conductor.service 2>/dev/null || true
sudo pkill -f 'uvicorn conductor' 2>/dev/null || true
sleep 1
sudo systemctl enable --now conductor.socket
sudo nginx -t && sudo systemctl reload nginx

# Verify
curl -fsS http://127.0.0.1:9093/health
echo "Deployed: $REL"

Execute from Windows¶

# Upload and run the deploy script
scp deploy-script.sh konstant:/tmp/deploy-script.sh
ssh konstant "bash /tmp/deploy-script.sh"

The pattern is always: write a bash script → scp it to the server → ssh and execute. This avoids PowerShell eating $() and -u flags in inline SSH commands.

Verify¶

curl https://conductor-konstant.hectorsanchez.eu/health
# {"status":"ok","service":"conductor","version":"0.2.0","connect":"/connect"}

curl -s -o /dev/null -w "%{http_code}" https://conductor-konstant.hectorsanchez.eu/
# 200

curl -s -o /dev/null -w "%{http_code}" https://conductor-docs.hectorsanchez.eu/
# 200

Release directory layout¶

/srv/apps/conductor/
├── current → releases/20260727T192904Z    # symlink to active release
├── releases/
│   ├── 20260727T185813Z/
│   └── 20260727T192904Z/
└── shared/
    ├── venv/                               # Python virtual environment
    ├── repo/                               # Git clone of conductor
    ├── .env                                # Environment secrets
    └── conductor.sqlite                    # Runtime database

/srv/apps/conductor-docs/
├── current → releases/20260727T184112Z
└── releases/
    └── 20260727T184112Z/                   # Static site files

Endpoints¶

Path	Auth	Purpose
`/`	Open	Landing page with agent configs
`/health`	Open	Health check (JSON)
`/connect`	Open	Full connection guide (HTML)
`/connect.md`	Open	Connection guide (raw markdown)
`/mcp`	Bearer token or `?key=`	MCP endpoint

Troubleshooting¶

Problem	Check
Service down after deploy	`ssh konstant "sudo systemctl status conductor.socket"`
Socket won't start	`ssh konstant "sudo journalctl -u conductor.socket -n 20"`
401 on landing page	Auth middleware may be blocking; check `_OPEN_EXACT` in `auth.py` includes `"/"`
Docs site stale	Rebuild MkDocs locally and redeploy `site/`
pip install fails	The shared venv may need updating: `ssh konstant "$APP/shared/venv/bin/pip install -r $APP/current/requirements.txt"`