Deploy docs to a VPS

The repository can build the VitePress docs in GitHub Actions and upload the static files to a VPS over SSH. This keeps the app repository private while still updating the docs on every push to main.

The workflow file is .github/workflows/docs-vps.yml.

Deployment target

The intended target is:

Setting	Value
Host	edgarcosta.ch
SSH user	edgar
SSH port	5678
Docs domain	finance-app.docs.edgarcosta.ch
Deploy path	/var/www/finance-app-docs

The docs are built with DOCS_BASE=/, so they are served from the root of the subdomain.

Create a deploy SSH key

Create a key on your local machine:

ssh-keygen -t ed25519 -C "github-actions-finances-docs" -f ~/.ssh/finances_app_docs_deploy -N ""

Install the public key on the VPS:

ssh server 'mkdir -p ~/.ssh && chmod 700 ~/.ssh'
cat ~/.ssh/finances_app_docs_deploy.pub | ssh server 'cat >> ~/.ssh/authorized_keys && chmod 600 ~/.ssh/authorized_keys'

Prepare the deploy directory:

ssh server 'sudo mkdir -p /var/www/finance-app-docs && sudo chown -R edgar:edgar /var/www/finance-app-docs'

Test the key:

ssh -i ~/.ssh/finances_app_docs_deploy -p 5678 edgar@edgarcosta.ch 'echo docs deploy ok'

Add GitHub Actions variables and secrets

In GitHub, open:

Settings -> Secrets and variables -> Actions

Add these repository variables:

Variable	Value
DOCS_DEPLOY_ENABLED	true after the key and server directory are ready
DOCS_DEPLOY_HOST	edgarcosta.ch
DOCS_DEPLOY_USER	edgar
DOCS_DEPLOY_PORT	5678
DOCS_DEPLOY_PATH	/var/www/finance-app-docs

Add this repository secret:

Secret	Value
DOCS_DEPLOY_SSH_KEY	The full contents of ~/.ssh/finances_app_docs_deploy

Keep DOCS_DEPLOY_ENABLED unset or set to false until the key and deploy directory are ready. The workflow will still build the docs, but it will skip the VPS upload.

Configure Caddy

After DNS points finance-app.docs.edgarcosta.ch at the VPS, add a Caddy site:

finance-app.docs.edgarcosta.ch {
    root * /var/www/finance-app-docs
    encode zstd gzip
    try_files {path} {path}.html {path}/index.html
    file_server
}

Reload Caddy after validating the config.