Self Hosting

Self-hosting Voyzu is currently untested. Treat this guide and the deployment command as a best-effort starting point, validate the installation in a non-production environment, and raise a GitHub issue if you encounter problems.

This guide deploys Voyzu from scratch to a single Linux server. It uses:

• PostgreSQL for the database

• systemd to run Voyzu

• Nginx as the public reverse proxy

• Certbot for HTTPS certificates

The commands below target a current Ubuntu or Debian server. The same layout works on other systemd-based distributions, but package installation commands will differ.

1. Prepare a server and domain

Create a server with a stable public IP address and enough memory and disk for Node.js, a production build, PostgreSQL, and database backups.

At the network firewall, allow inbound traffic on:

• 22/tcp for SSH, or your chosen SSH port

• 80/tcp for HTTP and the initial certificate challenge

• 443/tcp for HTTPS

Do not expose the Voyzu application port (3000) or PostgreSQL (5432) to the internet.

Create an A record for the Voyzu hostname that points to the server. Add an AAAA record only when the server has working public IPv6. The examples below use voyzu.example.com; replace it with your hostname.

Confirm DNS before requesting a certificate:

dig +short voyzu.example.com

2. Create the deployment user

Connect using the initial account supplied with the server. Create a dedicated account and copy the current account's authorized SSH keys:

sudo adduser --disabled-password --gecos "" voyzu
sudo usermod -aG sudo voyzu
sudo install -d -m 0700 -o voyzu -g voyzu /home/voyzu/.ssh
sudo cp "$HOME/.ssh/authorized_keys" /home/voyzu/.ssh/authorized_keys
sudo chown voyzu:voyzu /home/voyzu/.ssh/authorized_keys
sudo chmod 0600 /home/voyzu/.ssh/authorized_keys

The deployment script installs the environment file and systemd service, so this account requires non-interactive sudo:

echo 'voyzu ALL=(ALL) NOPASSWD: ALL' | sudo tee /etc/sudoers.d/voyzu-deploy
sudo chmod 0440 /etc/sudoers.d/voyzu-deploy
sudo visudo -cf /etc/sudoers.d/voyzu-deploy

Protect this account's SSH key as a privileged deployment credential. Test a new connection before closing the original session:

ssh [e-mail]
sudo -n true

3. Install server software

On the server, install the base packages, PostgreSQL, Nginx, and Snap support for Certbot:

sudo apt update
sudo apt upgrade -y
sudo apt install -y ca-certificates curl git nginx openssl postgresql postgresql-client snapd
sudo systemctl enable --now nginx postgresql

Voyzu requires Node.js 20.9 or newer and is currently developed against Node.js 24. Install Node.js system-wide so it is available to non-interactive SSH and systemd sessions. For example, using the NodeSource Debian/Ubuntu packages:

curl -fsSL https://deb.nodesource.com/setup_24.x -o /tmp/nodesource_setup.sh
sudo -E bash /tmp/nodesource_setup.sh
sudo apt install -y nodejs

Verify the installed tools:

node --version
npm --version
git --version
psql --version
nginx -v

If the server uses UFW, allow SSH before enabling it:

sudo ufw allow OpenSSH
sudo ufw allow 'Nginx Full'
sudo ufw enable
sudo ufw status

For a non-standard SSH port, allow that port explicitly instead of relying on the OpenSSH profile.

4. Create the PostgreSQL database

Keep PostgreSQL bound to the local server. Generate a strong password; hexadecimal output is convenient because it does not need URL encoding in the connection string:

openssl rand -hex 24
sudo -u postgres psql

In psql, create the application role and database, replacing the example password:

CREATE ROLE voyzu_app WITH LOGIN PASSWORD 'replace-with-generated-password';
CREATE DATABASE voyzu OWNER voyzu_app;
\q

Test password authentication locally:

psql 'postgresql://voyzu_app:replace-with-generated-password@127.0.0.1:5432/voyzu' -c 'select current_database();'

5. Create the production environment file

On the computer from which deployments will run, create a file outside the repository, for example voyzu.production.env:

VOYZU_DATABASE_URL=postgresql://voyzu_app:replace-with-generated-password@127.0.0.1:5432/voyzu
VOYZU_AUTH_SECRET=<generated-base64url-value>

When this environment is not based on a create-voyzu installation, generate the authentication secret with:

node -e "console.log(require('node:crypto').randomBytes(32).toString('base64url'))"

Voyzu has no default authentication secret and rejects missing values or values that decode to fewer than 32 bytes. The file must use shell-compatible KEY=VALUE syntax. Keep it out of Git and restrict local access to it. Add optional capability configuration to the same file when required.

6. Deploy Voyzu

Run deployments from a local Voyzu repository. If you do not already have one:

git clone --branch main --single-branch https://github.com/chrisjameslennon/voyzu.git
cd voyzu
npm ci

The deployment script creates a production Voyzu installation using create-voyzu. The platform is downloaded from the main branch of https://github.com/chrisjameslennon/voyzu.git.

First inspect the plan without connecting:

npm run deploy -- \
  --host voyzu.example.com \
  --user voyzu \
  --env-file /secure/path/voyzu.production.env \
  --dry-run

Then deploy:

npm run deploy -- \
  --host voyzu.example.com \
  --user voyzu \
  --env-file /secure/path/voyzu.production.env

On Windows PowerShell, enter the command on one line or use PowerShell backticks instead of backslashes.

The script:

1. Uploads the environment to /etc/voyzu/voyzu.env with restricted permissions.

2. Stops an existing Voyzu service before changing its runtime.

3. Creates /home/voyzu/voyzu as a production installation on the first run, or fast-forwards its platform checkout on later runs.

4. Checks the configured database and applies the preinstalled platform installation when it has not yet been initialized.

5. Installs or updates @voyzu/core, including its database installation and composed application registrations.

6. Builds the composed web application and prunes development dependencies.

7. Installs and enables voyzu.service under systemd.

8. Starts Voyzu on 127.0.0.1:3000 and performs a local health check.

The deployed directory is an installation root. Its platform checkout is at /home/voyzu/voyzu/.run/voyzu, and installed packages are beneath /home/voyzu/voyzu/.run/packages.

The platform checkout must be clean apart from composition output managed by Voyzu. Use --help to see options for an SSH key, SSH port, service name, deployment directory, or application port:

npm run deploy -- --help

Voyzu uses Puppeteer for PDF generation. Dependency installation downloads the browser as the deployment user. On a new Debian or Ubuntu server, also install the browser's operating-system dependencies. Keep Puppeteer's cache under the service user's home directory:

ssh [e-mail]
sudo env HOME=/home/voyzu PUPPETEER_CACHE_DIR=/home/voyzu/.cache/puppeteer \
  /home/voyzu/voyzu/.run/node_modules/.bin/puppeteer \
  browsers install chrome-headless-shell --install-deps
sudo chown -R voyzu:voyzu /home/voyzu/.cache/puppeteer

This is a host setup step and does not need to run with every deployment.

7. Verify initialization

The deployment command initializes the preinstalled platform packages and installs Core before starting the service. For a new empty database it also creates the bootstrap administrator:

User code: ADMIN
Password:  password

Confirm the generated installation, Core package, database connection, and service:

ssh [e-mail]
cd /home/voyzu/voyzu
sudo systemctl status voyzu
set -a
. /etc/voyzu/voyzu.env
set +a
npm run voyzu:list-packages
curl --fail http://127.0.0.1:3000/ >/dev/null

Sign in through the HTTPS endpoint after completing the proxy configuration. Create a named administrator with a strong unique password, verify that account can sign in, and delete the bootstrap ADMIN user before allowing normal access.

8. Configure Nginx

The repository includes an example site at infra/deploy/nginx.conf.example. Copy it to the server:

scp infra/deploy/nginx.conf.example [e-mail]:/tmp/voyzu.nginx.conf
ssh [e-mail]
sudo cp /tmp/voyzu.nginx.conf /etc/nginx/sites-available/voyzu
sudo editor /etc/nginx/sites-available/voyzu

Replace voyzu.example.com if necessary. If the deployment used a different application port, update the proxy_pass port as well.

Enable the site and remove the default site:

sudo ln -s /etc/nginx/sites-available/voyzu /etc/nginx/sites-enabled/voyzu
sudo rm -f /etc/nginx/sites-enabled/default
sudo nginx -t
sudo systemctl reload nginx
curl --head http://voyzu.example.com/

Nginx is the only public application endpoint. It forwards the original host, scheme, and client address to Voyzu and disables response buffering so Next.js streaming responses are not held by the proxy.

9. Enable HTTPS with Certbot

The hostname must resolve publicly to this server and port 80 must be reachable before this step. Install Certbot using its recommended Snap package:

sudo snap install core
sudo snap refresh core
sudo snap install --classic certbot
sudo ln -sf /snap/bin/certbot /usr/local/bin/certbot

Request the certificate and allow Certbot to update the Nginx site:

sudo certbot --nginx -d voyzu.example.com
sudo nginx -t
sudo systemctl reload nginx

Choose the HTTP-to-HTTPS redirect when prompted. Confirm renewal works:

sudo certbot renew --dry-run

Finally, browse to https://voyzu.example.com, sign in, and replace or disable all seeded credentials.

10. Operate and update Voyzu

Inspect the application and proxy:

sudo systemctl status voyzu
sudo journalctl -u voyzu -n 100 --no-pager
sudo tail -n 100 /var/log/nginx/voyzu.error.log
curl --head http://127.0.0.1:3000/

For later releases, rerun the deployment command. It fast-forwards the platform, updates Core from the Voyzu Packages repository, rebuilds the composed application, and restarts the service. Omit --env-file to retain the existing remote environment file:

npm run deploy -- --host voyzu.example.com --user voyzu

Back up PostgreSQL before deploying changes that affect the database:

sudo install -d -m 0700 -o postgres -g postgres /var/backups/voyzu
sudo -u postgres pg_dump --format=custom --file=/var/backups/voyzu/voyzu-$(date +%F).dump voyzu

Store backups outside the server and test the restore process. Also keep the operating system, Node.js, PostgreSQL, Nginx, and Certbot patched.

References

• Next.js self-hosting guide

• Nginx proxy module

• NodeSource Node.js packages

• PostgreSQL packages for Ubuntu

• Puppeteer installation and troubleshooting

• Certbot instructions for Nginx