Day Two Operations

Day-two operations

Updating

Read the CHANGELOG entry for the version you are moving to before you run anything. Releases carry an "Action required" section when they need something from you, and skipping it is how an upgrade half-works. Two recent examples: 3.12.0 needs INTERNAL_ALERT_TOKEN set on both the waf and backend services, or the WAF drops its block notifications silently; 3.13.0 makes GET /api/docs require authentication.

cd secure-proxy-manager
git pull
# read the new CHANGELOG entries, apply anything under "Action required" to .env
docker compose up -d --build

.env, the database and the blacklists live in bind-mounted volumes and survive the update. The backend checks GitHub for newer releases and shows a badge in the UI when one exists.

Backup and restore

All state is in three places: the database under data/, the configuration under config/, and .env.

docker compose down
cp data/proxy_manager.db proxy_manager.db.bak
tar czf config.bak.tgz config/ .env
docker compose up -d

Stopping first matters: SQLite copied while the backend is writing can give you a file that restores into a subtly broken state.

Two things to keep in mind about what you have just created:

• config/ contains the SSL-bump CA private key. Your backup is now as sensitive as the deployment. Encrypt it, and do not put it in a shared drive
• .env contains the admin password and the JWT signing secret

The UI also offers configuration export and import under Settings, and the database can be exported through the API. Those are convenient, but the file-level copy above is the one that restores a whole deployment.

Health checks

curl -skI https://localhost:8443/            # UI, self-signed certificate
curl -I http://127.0.0.1:5001/health         # backend, localhost only
curl -x http://localhost:3128 -I http://example.com    # proxy actually proxying

The third one is the interesting check: the first two can pass while the proxy path is broken.

The end-to-end suite

bash tests/ci-e2e.sh

Covers service health, proxy egress, blocking and the log pipeline. This is the check worth running after an update, because it exercises the path between the containers rather than each container on its own.

Component tests, when you are changing code:

cd backend-go && go test ./...
cd waf-go && go test ./...
cd ui && npm test
bash scripts/pre-commit-validate.sh    # TypeScript, ESLint, go vet and test, UI build

When the backend will not start

Check its log first:

docker compose logs backend

The most common cause is deliberate: the backend refuses an empty, common or shorter-than-8-character BASIC_AUTH_PASSWORD, and a SECRET_KEY that is a known or example value. It is failing closed rather than starting with a guessable credential.

When the UI is unreachable

It is HTTPS on 8443 with a self-signed certificate. Use https://localhost:8443 and accept the certificate. http://...:8011 is the HTTP redirect and the ACME challenge path, not the UI.

Rotating the admin credential

Settings, Change Password. This is the normal path and it works; the bug that made it silently fail (#230) is fixed. Verify afterwards that the old password is actually rejected — worth doing after any credential rotation, not because this one is suspect.

Editing BASIC_AUTH_PASSWORD in .env and restarting still works, and is the way in if you are locked out.