Public site · installer and docs

VPS Deployer

Docs

Troubleshooting

vps-deployer doctor
vps-deployer status
systemctl status vps-deployer
journalctl -u vps-deployer
journalctl -u vps-deployer-app-my-next-app

Installer log: /var/log/vps-deployer/installer.log.

The "no new privileges" flag is set

Versions before 0.3.5 applied NoNewPrivileges=true to the platform service even though privileged systemd, nginx, and certificate operations use its restricted sudo helper. Update VPS Deployer and verify the platform unit:

sudo vps-deployer update
systemctl show vps-deployer -p NoNewPrivileges

The result should be NoNewPrivileges=no. Application units continue to use NoNewPrivileges=true.

repository ... no longer has a Release file

APT stops when any configured Ubuntu or third-party repository is invalid, even when that repository is unrelated to VPS Deployer. Find the source:

grep -Rls 'the-host-or-repository-from-the-error' \
  /etc/apt/sources.list /etc/apt/sources.list.d 2>/dev/null

Disable or correct the reported source, run sudo apt-get update, and retry. Existing VPS Deployer installations skip APT during updates when all required dependencies are already installed. Prefer a supported Ubuntu LTS release because short-lived releases can lose third-party repository support.

Permission denied: '/etc/vps-deployer/config.env'

The config directory must be root:vps-deployer mode 770 and config.env mode 640 so the service user and the installing admin can read and write GitHub App files. Re-download install.sh and run it again, or fix the live VPS:

sudo chown root:vps-deployer /etc/vps-deployer
sudo chmod 770 /etc/vps-deployer
sudo chown vps-deployer:vps-deployer /etc/vps-deployer/config.env
sudo chmod 640 /etc/vps-deployer/config.env
sudo usermod -aG vps-deployer "$USER"

Start a new SSH session (or newgrp vps-deployer) so the group applies. Until then, sudo vps-deployer dashboard works.

Permission denied: '/etc/vps-deployer/ssl.json'

Upgrade to 0.3.6 or repair the existing state:

sudo chown vps-deployer:vps-deployer /etc/vps-deployer/ssl.json
sudo chmod 600 /etc/vps-deployer/ssl.json
sudo systemctl restart vps-deployer

failed to open file .../uv.toml

The installer ran uv from your home directory. Re-download install.sh from this site and run it again. Until that build is live, cd /tmp first:

cd /tmp
sudo bash /path/to/install.sh

The public website is down

Deploy, rollback, logs, and the local dashboard still work. You only need the internet for GitHub, Let's Encrypt, DNS, and downloading updates.

Unsupported operating system

Supported: Ubuntu 22.04 LTS or a newer LTS release, and Debian 12+. See Requirements.

Port 5100 already in use

Stop the old uvicorn or vps-deployer.service process, then start the current one. The local dashboard is GET / on that port.

HTTPS fails

Confirm DNS points at this VPS, port 80 is reachable, and you re-ran ssl enable after adding the hostname.

This website distributes the installer and documentation. It does not register your VPS, store credentials, or run deployments.

After install, your VPS keeps working if this site is down. Changelog