proxpanel/DEPLOYMENT.md

ProxPanel Deployment Guide (Production Ubuntu)

1) Hands-Free Production Install (Recommended)

Run this on your Ubuntu server:

sudo apt-get update -y
sudo apt-get install -y git
git clone <YOUR_REPO_URL> /opt/proxpanel
cd /opt/proxpanel
sudo bash infra/deploy/install-proxpanel.sh \
  --branch main \
  --public-url http://102.69.243.167 \
  --admin-email admin@yourdomain.com \
  --configure-ufw

If the repo already exists on the server, just run:

cd /opt/proxpanel
sudo bash infra/deploy/install-proxpanel.sh \
  --branch main \
  --public-url http://102.69.243.167 \
  --admin-email admin@yourdomain.com \
  --configure-ufw

Installer behavior:

• Installs Docker + prerequisites.
• Builds and starts PostgreSQL, backend, frontend.
• Applies Prisma schema (prisma:deploy, fallback to prisma:push).
• Seeds admin user.
• Verifies API health and login.
• Writes deployment summary to /root/proxpanel-install-summary.txt.

2) Fast Production Checks

cd /opt/proxpanel
docker compose --env-file .env.production -f infra/deploy/docker-compose.production.yml ps
curl -fsS http://127.0.0.1:8080/api/health
curl -I http://102.69.243.167

3) Connect Proxmox Cluster In App

A. Create Proxmox API token

In Proxmox UI:

1. Open Datacenter -> Permissions -> API Tokens.
2. Select your user (for example root@pam or a dedicated service user).
3. Click Add.
4. Set Token ID (example: proxpanel).
5. Copy the generated token secret immediately.

B. Save credentials in ProxPanel

In ProxPanel UI:

1. Login as admin.
2. Go to Settings -> Proxmox.
3. Fill:
   • Host: Proxmox hostname or IP (no https:// prefix)
   • Port: 8006
   • Username: e.g. root@pam
   • Token ID: e.g. proxpanel
   • Token Secret: generated secret
   • Verify SSL: enabled if Proxmox cert is trusted; disable only if using self-signed cert temporarily
4. Click Save Proxmox.

C. Trigger first sync

Use API once to import nodes/VMs:

APP_URL="http://102.69.243.167"
ADMIN_EMAIL="admin@yourdomain.com"
ADMIN_PASSWORD="<YOUR_ADMIN_PASSWORD>"

TOKEN=$(curl -s -X POST "$APP_URL/api/auth/login" \
  -H "Content-Type: application/json" \
  -d "{\"email\":\"$ADMIN_EMAIL\",\"password\":\"$ADMIN_PASSWORD\"}" | jq -r '.token')

curl -s -X POST "$APP_URL/api/proxmox/sync" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json"

Then confirm:

• Nodes page shows imported nodes.
• Dashboard cards and usage graphs populate.

4) Security Hardening Checklist

• Set a DNS name and terminate TLS (Nginx/Caddy/Cloudflare).
• Change the seeded admin password immediately.
• Keep CORS_ORIGIN set to your real public URL only.
• Use a dedicated Proxmox API user/token with least privileges.
• Keep backend bound to localhost (127.0.0.1) and expose only frontend port.
• Enable off-host backups for DB and app config.

5) PAT-Only Git Update Workflow (No Password Auth)

Use Personal Access Token (PAT) authentication only. Do not use account passwords for Git pull/push.

A. Create PAT (Git server)

1. Sign in to your Git server user settings.
2. Create a PAT with minimum required scopes (repo:read for pull; add write only if needed).
3. Save it securely (password manager/secret vault).

B. Update app on server with PAT (no credential persistence)

Run this on the server:

cd /opt/proxpanel
chmod +x infra/deploy/git-pat-sync.sh
export GIT_USERNAME="your_git_username"
export GIT_PAT="your_personal_access_token"
bash infra/deploy/git-pat-sync.sh \
  --repo-dir /opt/proxpanel \
  --branch main \
  --repo-url https://git.votcloud.com/austindebest/proxpanel.git
unset GIT_PAT

Then deploy:

cd /opt/proxpanel
docker compose --env-file .env.production -f infra/deploy/docker-compose.production.yml up -d --build