openpetswithchatandmcp/website/docs/ops/DEPLOYMENT_RUNBOOK.md

FamiliarOS Website Deployment Runbook

Production target

• VPS: 212.227.13.220 (Ubuntu 24.04)
• Web root: /var/www/familiaros
• NGINX config: /etc/nginx/sites-available/familiaros.conf
• Primary domains: familiar-os.com, www.familiar-os.com
• Deploy script: /home/dev/familiaros-deploy/deploy-website.sh
• Cross-project VPS guidance: /home/dev/familiaros-deploy/SERVER_INSTANCE_GUIDANCE.md (also in the ScriptoriumAI repo at docs/ops/FAMILIAROS_SERVER_INSTANCE_GUIDANCE.md)

One-time prerequisites

1. Node.js 22 and npm are installed on the build machine.
2. The VPS has nginx installed and the site config points /var/www/familiaros.
3. The dev user can run sudo (password required) or you have a root shell.
4. GitHub OAuth is currently disabled by default (VITE_GITHUB_OAUTH_ENABLED=false).

Environment variables

The following variables are baked into the production bundle at build time. Set them before running npm run build.

Variable	Production example
VITE_SUPERTOKENS_API_DOMAIN	https://api.familiar-os.com
VITE_SUPERTOKENS_WEBSITE_DOMAIN	https://familiar-os.com
VITE_SUPERTOKENS_API_BASE_PATH	/auth
VITE_SUPERTOKENS_WEBSITE_BASE_PATH	/auth
VITE_AUTH_API_BASE_URL	https://api.familiar-os.com
VITE_GITHUB_OAUTH_ENABLED	false

GitHub OAuth is currently disabled by default. See GITHUB_AUTH_STATUS.md for the rationale and enablement steps.

Manual deployment commands

From the project directory on the VPS (or via SSH):

cd /home/dev/src/FamiliarOSWebsite
npm ci
npm run build
sudo bash /home/dev/familiaros-deploy/deploy-website.sh

If you are logged in as dev and sudo requires a password, the last command will prompt for the dev account password. To avoid the prompt, run the commands from a root shell instead.

What the deploy script does:

1. Syncs dist/ to /var/www/familiaros with rsync --delete.
2. Sets ownership to www-data:www-data.
3. Updates the nginx config to serve clean URLs (e.g. /pricing → /pricing.html).
4. Runs nginx -t and systemctl reload nginx.
5. Prints smoke-test HTTP codes for the main pages.

CI/CD deployment

The repository includes .github/workflows/deploy.yml. It runs on every push to main or on manual dispatch.

Required GitHub repository secrets:

Secret	Purpose
VPS_HOST	VPS IP or hostname (212.227.13.220)
VPS_USER	SSH user (dev)
VPS_SSH_KEY	Private SSH key with access to the VPS

Required GitHub repository variables:

Variable	Purpose
VITE_SUPERTOKENS_API_DOMAIN	Public SuperTokens API origin
VITE_SUPERTOKENS_WEBSITE_DOMAIN	Public website origin
VITE_AUTH_API_BASE_URL	Auth API origin used by the frontend
PRIMARY_DOMAIN	Domain used for smoke-test curls (familiar-os.com)

Optional variables: VITE_GITHUB_OAUTH_ENABLED (default false), VITE_AUTH_API_TIMEOUT_MS, VITE_AUTH_HEALTH_TIMEOUT_MS.

Auth backend deployment

The SuperTokens self-hosted backend is in the server/ directory.

cd /home/dev/src/FamiliarOSWebsite/server
npm ci
docker compose up -d
npm run start

For production, run the Node process under pm2 or a systemd service instead of npm run start. The live VPS already uses the systemd unit familiaros-auth-server.service, which points the backend at the SuperTokens core on http://127.0.0.1:3568 (host port 3568 is used to avoid colliding with the ScriptoriumAI core on port 3567).

GitHub OAuth remains disabled until GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET are added to server/.env.

Smoke tests

After deployment, verify the main pages return 200:

curl -s -o /dev/null -w "https://familiar-os.com/ -> %{http_code}\n" https://familiar-os.com/
curl -s -o /dev/null -w "https://familiar-os.com/pricing -> %{http_code}\n" https://familiar-os.com/pricing
curl -s -o /dev/null -w "https://familiar-os.com/about -> %{http_code}\n" https://familiar-os.com/about