dark-lord/DEPLOY.md

CyberLux — production on Tor (.onion)

This app is designed to run behind nginx on loopback, with one Tor v3 hidden service for the whole site. Nginx listens on 127.0.0.1:8080 (see scripts/onion-nodes.json); Tor forwards port 80 on the onion to that loopback port. Next.js binds only 127.0.0.1:3000 — never expose 3000 or the nginx loopback port to the public internet.

Onion hostnames are created locally when Tor first starts; there are no fixed .onion URLs in the repo. Back up /var/lib/tor/cyberlux/hs_ed25519_secret_key (the install flow uses scripts/backup-onion-keys.sh). A vanity prefix such as cyberlux...onion requires generating or importing a matching Tor v3 hidden-service key.

One-time server setup (Debian/Ubuntu-style)

sudo apt update
sudo apt install -y tor nginx curl nodejs npm build-essential
# Or install Node.js LTS from NodeSource / nvm — `node` and `npm` must be on PATH.

Deploy the app

From the repo root (as the user that will own the process):

./start.sh

This will: regenerate Tor/nginx maps from scripts/onion-nodes.json, npm install, npm run build, install Tor+nginx configs (sudo), wait for the hostname file, print the .onion URL, then foreground next start on 127.0.0.1:3000.

For a one-shot prepare (build + Tor/nginx, no Next.js — for systemd):

CYBERLUX_PREPARE_ONLY=1 ./start.sh

systemd — start on boot

1. Ensure ./start.sh or CYBERLUX_PREPARE_ONLY=1 ./start.sh has been run at least once so .next exists and Tor directories are populated.
2. Install the unit (run as root; set user to the account that owns the repo):

sudo CYBERLUX_USER=youruser bash scripts/install-systemd.sh
# optional: sudo CYBERLUX_CHOWN_REPO=1 CYBERLUX_USER=youruser bash scripts/install-systemd.sh

3. Enable Tor, nginx, and CyberLux at boot:

sudo systemctl enable tor.service nginx.service cyberlux.service
# if your distro uses tor@default instead of tor:
# sudo systemctl enable tor@default.service nginx.service cyberlux.service
sudo systemctl start tor.service nginx.service cyberlux.service

4. Check logs:

journalctl -u cyberlux.service -f

5. Health check (local):

npm run health:stack

6. List the .onion URL and check that the nginx loopback vhost answers (needs Tor running; use sudo if hostname files are root-only):

npm run onions:status
# or:
sudo node scripts/onion-status.cjs

Changing the onion map

1. Edit scripts/onion-nodes.json.
2. Run node scripts/generate-onion-config.cjs (or npm run build, which runs it in prebuild).
3. sudo bash scripts/install-tor-onion.sh
4. Rebuild/restart the app: npm run build and sudo systemctl restart cyberlux.service

502 Bad Gateway on .onion sites

Tor and nginx are working, but nginx proxies to Next.js on 127.0.0.1:3000. A 502 means nothing is listening there (Next is stopped, crashed, or never started after reboot).

1. Confirm (from the repo):

   curl -sS -o /dev/null -w "%{http_code}\n" http://127.0.0.1:3000/
   

   000 = connection refused → Next is down.

2. Start Next (pick one):

   • Foreground (dev / quick test): cd /path/to/cyberlux && npm run start:onion — leave the terminal open.
   • systemd (production): sudo systemctl start cyberlux.service — ensure the unit is installed (scripts/install-systemd.sh) and enabled.
   • Full stack script: ./start.sh (builds, configures Tor/nginx if needed, then starts Next).

3. Verify again:

   npm run health:stack
   

   You want Next.js: OK and hub vhost: OK (HTTP 200/301/302/304).

4. If it still fails: journalctl -u cyberlux.service -n 80 --no-pager — look for crash loops, missing .next (run npm run build), or wrong WorkingDirectory in the unit.

Custom .onion prefix (branded / vanity name)

v3 hostnames are random unless you mine a key with mkp224o and install it. That is a separate, long-running CPU step — not part of a normal deploy.

1. bash scripts/mkp224o-build.sh (or Docker; see ONION-URLS.md)
2. bash scripts/vanity-onion-mine.sh <base32_prefix>
3. sudo bash scripts/install-vanity-onion-key.sh var/vanity-mine

Full details: ONION-URLS.md.

Verification

npm run verify

Security & compliance

• You are responsible for local law, hosting terms, and Tor / relay policies. This repo is a parody web app; treat operational security seriously if you run it on a real server.

Security notes

• Only Tor should be reachable from outside; bind nothing to 0.0.0.0 for this stack.
• Prefer firewall defaults that deny incoming except what you need for SSH.
• Optional: sudo bash scripts/classroom-ufw.sh (if present) for a restrictive UFW profile.