vault-dash/docs/DEVOPS_DEPLOY_PROMPT.md

DevOps Agent: Deploy Vault-Dash to VPS

Goal

Configure the deployment secrets and keys needed to deploy the vault-dash application from Forgejo CI/CD to a VPS.

Context

The vault-dash project is a Python/FastAPI/NiceGUI dashboard for options hedging analysis. The CI/CD pipeline runs on Forgejo Actions and currently fails at the build and deploy stages due to missing secrets.

Current Infrastructure

• Forgejo Server: http://git.uncloud.vpn (internal VPN address)
• Git URL: ssh://git@10.100.0.2:2222/bu5hm4nn/vault-dash.git
• Runner Labels: [linux, docker]
• Target Deployment: VPS (details to be determined)

Deployment Workflow

The .forgejo/workflows/deploy.yaml workflow has these stages:

1. lint → test → type-check → build → deploy

The build stage pushes to a Docker registry, and the deploy stage uses SSH to deploy to a VPS.

Required Secrets

1. Docker Registry Secrets

The build job needs:

• REGISTRY_PASSWORD (or falls back to GITHUB_TOKEN)
• REGISTRY environment variable (defaults to 10.100.0.2:3000)

env:
  REGISTRY: ${{ vars.REGISTRY || '10.100.0.2:3000' }}
  IMAGE_NAME: ${{ github.repository }}

# In docker/login-action:
username: ${{ github.actor }}
password: ${{ secrets.REGISTRY_PASSWORD || secrets.GITHUB_TOKEN }}

2. Deployment Secrets

The deploy job needs:

• DEPLOY_HOST - VPS hostname/IP address
• DEPLOY_USER - SSH user (defaults to deploy)
• DEPLOY_PORT - SSH port (defaults to 22)
• DEPLOY_PATH - Deploy path (defaults to /opt/vault-dash)
• DEPLOY_SSH_PRIVATE_KEY - SSH private key for authentication

env:
  DEPLOY_HOST: ${{ secrets.DEPLOY_HOST }}
  DEPLOY_USER: ${{ secrets.DEPLOY_USER || 'deploy' }}
  DEPLOY_PORT: ${{ secrets.DEPLOY_PORT || '22' }}
  DEPLOY_PATH: ${{ secrets.DEPLOY_PATH || '/opt/vault-dash' }}
  DEPLOY_SSH_PRIVATE_KEY: ${{ secrets.DEPLOY_SSH_PRIVATE_KEY }}
  APP_IMAGE: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ github.sha }}

Tasks

1. Determine VPS details: Where should the application be deployed? What's the host IP/hostname?

2. Create a deploy user on the VPS:

   • Create a deploy user with sudo privileges for Docker
   • Generate an SSH keypair for the deploy user
   • Configure the public key in the VPS ~/.ssh/authorized_keys

3. Add Forgejo secrets:

   • In Forgejo, go to Repository → Settings → Secrets
   • Add DEPLOY_HOST with the VPS address
   • Add DEPLOY_SSH_PRIVATE_KEY with the private key content
   • Add REGISTRY_PASSWORD if using the internal registry

4. Configure Docker on the VPS:

   • Ensure Docker and Docker Compose are installed
   • The deploy script will pull the container image from the registry
   • Ensure the shared external Docker network proxy-net exists so Caddy can reverse proxy the deployment by container name

5. Publish public route through Caddy:

   • Add lombard.uncloud.tech to /opt/caddy/Caddyfile
   • Reverse proxy to vault-dash:8000 on proxy-net
   • Reload Caddy and verify https://lombard.uncloud.tech/health
   • Remove the retired vd1.uncloud.vpn route if it still exists

6. Verify network connectivity:

   • Forgejo runner must be able to reach the VPS via SSH
   • VPS must be able to pull images from the registry

Instructions for the DevOps Agent

When setting up the deployment:

1. For the SSH key: Generate a dedicated deploy key (not a personal key):

   ssh-keygen -t ed25519 -f vault-dash-deploy-key -N "" -C "vault-dash-deploy@forgejo"
   

   The private key (vault-dash-deploy-key) goes into DEPLOY_SSH_PRIVATE_KEY secret. The public key (vault-dash-deploy-key.pub) goes into the VPS user's ~/.ssh/authorized_keys.

2. For the deploy user on VPS:

   # Create deploy user
   sudo useradd -m -s /bin/bash deploy
   
   # Add to docker group
   sudo usermod -aG docker deploy
   
   # Set up SSH directory
   sudo -u deploy mkdir -p /home/deploy/.ssh
   sudo -u deploy chmod 700 /home/deploy/.ssh
   
   # Add the public key
   echo "ssh-ed25519 AAAA... vault-dash-deploy@forgejo" | sudo -u deploy tee /home/deploy/.ssh/authorized_keys
   sudo -u deploy chmod 600 /home/deploy/.ssh/authorized_keys
   

3. For the Docker registry (if using internal Forgejo registry):

   • The registry must be accessible from both the runner and the VPS
   • The REGISTRY_PASSWORD can be the user's Forgejo token or a dedicated registry token

4. Create a dedicated deployment directory:

   sudo mkdir -p /opt/vault-dash
   sudo chown deploy:deploy /opt/vault-dash
   

Output

Please provide:

1. The VPS hostname/IP address
2. The SSH public key to add to the VPS
3. Confirmation of all secrets added to Forgejo
4. Any additional network or firewall configurations needed