documentation/procedures/pega-prox-deploy.md

Procedure: Deploy PegaProx on Docker Swarm

Scope: Deploy PegaProx (Proxmox VE cluster manager) as a Docker Swarm service on MK7. Author: F.R.I.D.A.Y. Date: 2026-05-31 Prerequisites: MK7 Swarm manager active, traefik-public overlay network exists.

---

1. Create Swarm Compose File

Save as /tmp/pegaprox_swarm.yml on MK7:

version: "3.8"
services:
  pegaprox:
    image: pegaprox/pegaprox:latest
    deploy:
      mode: replicated
      replicas: 1
      placement:
        constraints:
          - node.role == manager
    ports:
      - target: 5000
        published: 5000
        mode: host
        protocol: tcp
      - target: 5001
        published: 5001
        mode: host
        protocol: tcp
      - target: 5002
        published: 5002
        mode: host
        protocol: tcp
    networks:
      - traefik-public
    volumes:
      - pegaprox-config:/app/config
    environment:
      - PEGAPROX_DEBUG=0

volumes:
  pegaprox-config:
    driver: local

networks:
  traefik-public:
    external: true

Critical: mode: host is required. ingress mode breaks WebSocket VNC/SSH consoles because Swarm ingress routing does not support WebSocket upgrade properly.

---

2. Deploy Stack

ssh jarvis@mk7.ai.home
docker stack deploy -c /tmp/pegaprox_swarm.yml pegaprox

Verify:

docker service ls | grep pegaprox
docker ps | grep pegaprox

---

3. Verify Service Health

# HTTPS API
curl -sk https://192.168.7.7:5000/api/health

# Check container logs
docker logs $(docker ps -q -f name=pegaprox)

Expected: {"status":"ok"}

---

4. First Login & Password Change

1. Open https://192.168.7.7:5000
2. Login with default credentials:
   • Username: pegaprox
   • Password: admin
3. System will force password change on first login
4. API returns: {"security_warning":"DEFAULT_PASSWORD","requires_password_change":true}

---

5. API Notes for Automation

CSRF Protection

All state-changing API calls (POST/PUT/PATCH/DELETE) must include:

X-Requested-With: XMLHttpRequest

Exempt paths (no CSRF header needed):

• /api/auth/login
• /api/auth/setup
• /api/auth/oidc/*
• /api/auth/check
• /api/auth/validate
• /api/auth/logout
• /api/health
• /api/webauthn/auth/begin

Add Cluster

curl -sk -X POST https://192.168.7.7:5000/api/clusters \
  -b cookies.txt \
  -H "Content-Type: application/json" \
  -H "X-Requested-With: XMLHttpRequest" \
  -d '{
    "name": "MK33",
    "host": "192.168.7.33",
    "user": "root@pam",
    "pass": "YOUR_PVE_PASSWORD"
  }'

CRITICAL: host must be bare IP only. Do NOT append :8006. PegaProx appends the port internally. Supplying 192.168.7.33:8006 causes URL parse failure: Failed to parse: https://[192.168.7.33:8006]:8006/...

---

6. Backup Volume

# Backup PegaProx config + DB
docker run --rm -v pegaprox_pegaprox-config:/src -v /tmp:/dst alpine \
  tar czf /dst/pegaprox-config-$(date +%Y%m%d).tar.gz -C /src .

---

7. Known Issues

Issue	Cause	Fix
WebSocket VNC/SSH broken	Swarm ingress mode strips upgrade headers	Use mode: host
URL parse error on add-cluster	:8006 appended to host field	Use bare IP only
CSRF 403 on API calls	Missing X-Requested-With header	Add header to all state-changing calls
Self-signed cert warning	No CA-signed cert deployed	Accept in browser or deploy custom cert

---

Rollback

ssh jarvis@mk7.ai.home
docker stack rm pegaprox
docker volume rm pegaprox_pegaprox-config  # WARNING: destroys all data

---

Last updated: 2026-05-31