deploy/

deploy/

Operational scripts and host configuration for running Nekomari. None of this is needed to use the project — it is the tooling used to deploy, verify and operate the reference instance, kept in-tree so the steps are reproducible rather than folklore.

No credentials belong in this directory. Tokens and passwords come from the panel or the environment; see docs/SECRETS.md for why, and for the incident that rule came from.

Deploy

Check

Why there is no hand-written contract validator

There was one: validate_contract.py, a Python mirror of the theme's zod schemas. It was deleted. It required classification to have type and label and nothing else, because that is what the server sent — so it validated the implementation against itself and passed while the real theme rejected the same payload for a missing classification.source. The IP 信息 tab stayed invisible and this script said everything was fine.

A transcription of a contract you cannot see is not a check. theme-contract-check.mjs extracts the schema from the installed bundle and runs it with the theme's own bundled zod, so it cannot agree with a bug in the server.

Browser checks

Run with Playwright against a live panel. Each drives the real UI rather than the API, because that is the only way to see what a user sees.

Setup

Needs Node 20+ and a Chromium download (~115 MB). From this directory:

npm install          # installs playwright (declared in deploy/package.json)
npm run setup        # playwright install chromium

Running

All four take the same arguments — panel URL, username, password, and optionally an output directory for screenshots:

node ip_panel_check.js    https://your-panel admin 'password' /tmp
node ip_panel_capture.js  https://your-panel admin 'password'
node favicon_ui_check.js  https://your-panel admin 'password' /tmp
node admin_version_check.js https://your-panel admin 'password'

The password goes on the command line, so it is visible in ps while the script runs and lands in your shell history. That is acceptable for a throwaway test account and not for a real one; see docs/SECRETS.md.

A panel with private_site enabled answers anonymous requests with 401, so the scripts log in through /api/login first rather than driving a login form.

Each exits non-zero if its own expectations fail, so they can be wired into a script; none of them are part of CI, because all four need a running panel and real credentials.

Themes

Cloudflare

The vhost trusts CF-Connecting-IP only when the connection really came from Cloudflare, and UFW admits 80/443 only from the same ranges. The two are complementary: the geo block stops a forged header, the firewall stops the direct connection that would carry it. Keep both halves in step — v4 and v6 are separate rule sets, and a half-configured pair fails quietly. When only the v4 rules exist, nothing breaks while the origin record is an A record, but the day an AAAA is added those origin fetches are dropped before nginx and show up as intermittent 522s with nothing in the origin's logs. --ufw exists because that gap was found in production.

CI maintenance

Actions pinned to a Node 20 runtime still run, but GitHub forces them onto Node 24 and warns on every job. These four make the upgrade a re-run rather than a research task, and they check the things that only fail at run time.

Watch out for one thing when bumping setup-go: go-version-file must point at the higher of the two modules' requirements. The root go.mod says 1.25.0 and agent/go.mod says 1.26.0, and both are built from the same job. Pointing at the root installed too old a toolchain and the agent tests failed with go.mod requires go >= 1.26.0. Older versions of the action tolerated the mismatch; v7 installs exactly what the file asks for, which is correct behaviour that simply exposed the wrong file being named.

Retiring the previous stack

See docs/RETIRE-CF-PROBE.md for the full record. These are kept because the rollback path matters more than the removal path.

Token rotation

Pushing the new tokens to each host depends on where the SSH keys live, so it is done per-reachability rather than by one script: some hosts are reachable from the panel host, others only from a workstation, one only over IPv6, and two need a sudo password. That variation is why the ad-hoc push scripts were removed once used — keeping them implied a single supported path that does not exist.

Script authentication, and what 2FA changes

Every script here that talks to the panel logs in through nekomari_auth.py, which handles TOTP. Enabling 2FA on the account breaks any script that logs in with just a username and password — they start returning 401 2FA code is required. That is not a bug in the scripts; it is 2FA working.

export NEKOMARI_PASSWORD='<panel password>'
export NEKOMARI_2FA_SECRET='<base32 secret from enrolment>'
sudo -n env NEKOMARI_PASSWORD="$NEKOMARI_PASSWORD" \
            NEKOMARI_2FA_SECRET="$NEKOMARI_2FA_SECRET" \
            python3 deploy/<script>.py

nekomari_auth.py implements RFC 6238 directly rather than depending on a TOTP library, so the scripts stay runnable on a host with nothing installed. If the variable is missing while 2FA is on, login fails with a message naming the variable instead of a bare 401.

enable-2fa.py enrols the account and prints the secret and otpauth:// URI; that secret is the only way back in short of the disable-2fa CLI.

hosts/

Per-host configuration that does not fit the generic installer.

experiments/

One-off probes kept because they captured knowledge that was otherwise expensive to obtain. Not part of any operational path.