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.