archadmin/archforge-external-statuspublic

Repository files, collaboration, releases and project activity.

Milestones Commits Wiki Discussions Projects Activity CODEOWNERS Arch Linux Insights

archforge-external-status / README.mdmain

▤ README.md15537 bytes

ArchForge External Status 1.0.8 — Debian 13 ArchForge Edition

New: .archforge ArchForge migration, see DEBIAN-13-GIT-URL-MIGRATION.md.

Release 1.0.8: consistent ArchForge service naming across the independent public and admin status website.

Independent uptime monitoring at https://status.archforge.nl. This software runs on a second VPS, without Docker, Pterodactyl, ArchForge credentials, or any database connection to the main website.

It does not modify the ArchForge main website. If archforge.nl becomes unreachable, the external service continues monitoring, saving independent history and sending alerts.

Nieuw in 1.0.6: veilige, aantoonbaar geïnstalleerde adminloginfix

Een browser met privacybescherming kan Origin of Referer normaliseren of afschermen. De server verwerkt nu browser-origininformatie met Sec-Fetch-Site, terwijl cross-site formulierverzoeken nog steeds worden geweigerd en elk POST-verzoek een CSRF-token nodig heeft. De bestaande scrypt-wachtwoordcontrole, TOTP-2FA, Secure cookies en rate limiting blijven actief.

Update via je eigen ArchForge-repository: pak de 1.0.6-update uit in de checkout op je pc, commit en push de wijzigingen. Op Debian 13 (als root):

cd ~/archforge-external-status
git pull --ff-only
bash ./repair-admin-login.sh

De herstelactie maakt een private back-up van status.env, corrigeert alleen STATUS_PUBLIC_URL als die afwijkt, deployt de geteste release met een bestaande databaseback-up en code-rollback, verifieert daarna de daadwerkelijk draaiende versie via /healthz én probeert drie onschuldige loginverzoeken zonder echte wachtwoorden: een gewone same-origin browser, een browser met privacyheader, en een geweigerd cross-site verzoek. Bij een mislukte controle meldt de tool precies welke fase faalde. Hij raakt geen adminwachtwoorden, TOTP of Caddy aan.

Zie FIX-ADMIN-LOGIN-1.0.6.md. Een geslaagde lokale test bewijst nog niet wat de browser op jouw apparaat verstuurt; als de 403 blijft, vermeld dan of de melding hetzelfde is en welke foutregel de herstelactie heeft getoond.

Nieuw in 1.0.5: adminlogin 403 Invalid origin oplossen

Als de browser na het inloggen op /admin/login de fout 403 Invalid origin toont, wordt de POST voor de wachtwoord- en 2FA-controle geblokkeerd. De app vergelijkt de herkomst met STATUS_PUBLIC_URL; een afwijkende (oude) instelling, of een geldig HTTPS-origin met expliciete standaardpoort 443, kon login blokkeren.

Pak versie 1.0.5 uit over de bestanden van je bestaande ArchForge-repository, commit en push. Start op VPS 2 (als root):

cd ~/archforge-external-status
git pull --ff-only
bash ./fix-admin-origin.sh

Deze herstelactie controleert de draaiende statusapp en Caddy-domeinconfiguratie, maakt een private back-up van status.env, synchroniseert zo nodig alleen STATUS_PUBLIC_URL, installeert de bijgewerkte code met de bestaande geteste deployer, en verifieert dat een HTTPS-loginformulier de origincheck passeert maar niet de CSRF-check. Wachtwoorden/2FA worden niet aangeraakt; de bestaande SQLite-database, incidenten en Caddy-configuratie blijven behouden. Zie FIX-ADMIN-403-1.0.5.md.

Nieuw in 1.0.4: HTTP 302 monitoringfix

De hoofdwebsite kan een HTTP 302 naar een andere pagina op hetzelfde HTTPS-domein teruggeven. Vóór 1.0.4 werd dit ten onrechte als outage beschouwd. De websitecheck volgt nu maximaal 3 veilige redirects en accepteert alleen een uiteindelijke HTTP 200. Dit controleert bereikbaarheid, niet alle websitefuncties. API en ArchForge-controles blijven strikt.

Als je al bent ingelogd als root op VPS 2, voer na commit/push van de 1.0.4-bestanden op je ArchForge-server uit:

cd ~/archforge-external-status
git pull --ff-only
bash ./apply-monitor-fix.sh

Dit hergebruikt de bestaande code-deployer, inclusief back-up en rollback bij een mislukte restart. De eerste geslaagde check start meteen na het herstarten; na standaard 2 succesvolle controles verdwijnt het bestaande automatische incident. Historische 302-fouten blijven in de uptimehistorie staan. Zie FIX-HTTP-302-1.0.4.md.

Nieuw in 1.0.3: directe HTTPS-reparatie

Wanneer Caddy alleen op :80 luistert en status.archforge.nl een Connection refused op :443 geeft, gebruik op VPS 2 na git pull --ff-only:

bash ./fix-https.sh

Deze root-only herstelactie controleert de lokale statusapp, back-upt /etc/caddy/Caddyfile, vervangt alleen op een dedicated status-VPS de standaard :80-configuratie door een direct HTTPS-domeinblok en herstart Caddy. Wanneer Caddy op :443 niet kan luisteren, herstelt hij de vorige configuratie en toont de concrete servicefout. Hij raakt /etc/archforge-status/status.env, SQLite en je adminaccount niet aan. Hij weigert een Caddy-setup met extra sites in /etc/caddy/conf.d/. Zie FIX-HTTPS-1.0.3.md.

Nieuw in 1.0.2: domein en SSL regelen na de installatie

Een aparte ArchForge-ready wizard koppelt een statusdomein aan de tweede Debian 13 VPS, controleert A/AAAA-records, configureert Caddy en verifieert de uitgegeven HTTPS-verbinding. De oude SQLite-, admin- en .env-instellingen blijven bestaan.

cd ~/archforge-external-status
git pull --ff-only
sudo bash ./configure-domain.sh

Als je al root bent, mag je bash ./configure-domain.sh gebruiken. Je hoeft ./install.sh of ./update.sh niet opnieuw te starten. Lees eerst DOMAIN-SSL-DEBIAN-13.md.

Admin wizard hotfix / interrupted v1.0.0 installation

If the old installer hangs after the admin username, do not delete the SQLite database or .env. Update your ArchForge checkout to this release (or copy the hotfix src/cli.js and recover-admin.sh into it), then, on VPS 2:

# If you are logged in as root:
cd ~/archforge-external-status
bash ./recover-admin.sh

# Or if logged in as a regular sudo user:
sudo bash ./recover-admin.sh

This only replaces the CLI wizard and finishes admin creation. It does not reinstall packages, restart the service, modify the config or overwrite an existing admin account. Read HOTFIX-ADMIN-1.0.1.md for details. sudo ./install.sh on an already running installation also delegates to this recovery script.

Security: v1.0.0's old stty/readline combination could echo the password. Use a fresh unique admin password, especially if the previous one was typed at that prompt.

Included

Independent checks for main HTTPS website, optional public API, optional public ArchForge HTTPS, ArchForge SSH banner, DNS, and HTTPS TLS certificate.
Startup and repeating checks (default every 60 seconds). Three failures to confirm an outage; two successes to confirm recovery.
Responsive dark-blue status website, 7/30/90-day history, incident timeline, per-service details, observed uptime and monitoring coverage.
Automatic outage incidents and recovery records; manual admin incident updates and scheduled public maintenance notices.
Discord webhook and email through the second VPS's own SMTP configuration. Confirmed subscriptions and unsubscribe links.
Independent admin credentials, password hashing with scrypt, TOTP authenticator 2FA, session-based CSRF protection.
SQLite WAL database outside the ArchForge repository; systemd service; Caddy HTTPS; root-controlled secrets.
ArchForge-based manual updates, local release snapshots, rollback.sh, daily SQLite backups, restore.sh and uninstall.sh.

Requirements

A clean Debian 13 (Trixie) VPS with root/sudo access, a network connection for packages, DNS control for status.archforge.nl, ports 80/443 inbound, and an SMTP account if email alerts are needed. By default Node.js 24 is installed via a signed NodeSource APT repository. sudo ./install.sh makes system-level changes; examine scripts before executing.

Step 1 — Put the project in ArchForge

Create a repository, e.g. archadmin/archforge-external-status. Unzip this project locally, then run:

git init
git branch -M main
git add .
git commit -m "Initial independent status server"
git remote add origin <ACTUAL_CLONE_URL_FROM_ARCHFORGE>
git push -u origin main

Do not commit a real .env, database, backup, SSH key or webhook token. .gitignore excludes local secrets. .env.example is a harmless template.

Step 2 — DNS (second VPS)

Add a DNS A record for status.archforge.nl pointing to the public IPv4 of VPS 2. Add an AAAA record only if the VPS has working public IPv6. Allow TCP 80 and 443 through provider firewall and OS firewall. Do not proxy the subdomain through VPS 1.

Existing install: branding repair (v1.0.9)

If your status page still shows Git SSH / Git Smart HTTP after upgrades, use the branding repair guide. No clean install is needed. The repair script only deploys the new application code and preserves the existing SQLite database, admin login, monitoring data and Caddy configuration.

Step 3 — Install on Debian 13

On VPS 2:

sudo apt-get update
sudo apt-get install -y git
# Use the clone URL displayed by YOUR ArchForge repository.
git clone <ACTUAL_CLONE_URL_FROM_ARCHFORGE> archforge-external-status
cd archforge-external-status
chmod +x install.sh
sudo ./install.sh

The interactive wizard checks Debian 13, installs ArchForge, SQLite, Node.js 24, Caddy, msmtp and other requirements, creates a dedicated archforge-status service user, asks for domain/targets, Discord webhook and optional SMTP. The wizard generates /etc/archforge-status/status.env and an encrypted TOTP secret in SQLite. You must pair an authenticator app and verify a six-digit code during initial admin setup.

Do not use sudo ./install.sh on the main VPS! Install it only on VPS 2.

Secrets and data are not in ArchForge

File	Purpose
`/etc/archforge-status/status.env`	Root-controlled configuration, encryption key, Discord webhook
`/etc/archforge-status/msmtprc`	Restricted SMTP client configuration
`/var/lib/archforge-status/status.db`	Independent SQLite database and admin credentials
`/opt/archforge-status/app`	Running, installed program code
`/var/backups/archforge-status/`	Private database and configuration backups

Do not lose the environment encryption key or TOTP recovery will fail. Backups include sensitive credentials and should be stored on an encrypted disk and ideally copied to a secure location outside VPS 2.

Step 4 — Confirm operation

sudo systemctl status archforge-status --no-pager
sudo journalctl -u archforge-status -n 80 --no-pager
curl -fsS http://127.0.0.1:3000/healthz
curl -I https://status.archforge.nl

Open https://status.archforge.nl, and log in at /admin/login with the separate admin credentials and TOTP. First-time uptime history starts empty; days without measurements are shown as Unknown, not as successful uptime.

If HTTPS is not issuing, verify DNS points to VPS 2, ports 80/443, sudo systemctl status caddy, and sudo journalctl -u caddy -n 80. The installer does not modify archforge.nl or its reverse proxy.

Operations

sudo systemctl restart archforge-status
sudo systemctl status archforge-status
sudo journalctl -u archforge-status -f
./update.sh             # run as the ArchForge checkout owner, NOT with sudo
./backup.sh             # invokes sudo
./rollback.sh           # restores previous installed application code
./restore.sh /var/backups/archforge-status/backup-YYYYMMDD-HHMMSS.tar.gz
sudo bash scripts/uninstall.sh

./update.sh fetches from the configured ArchForge remote using git pull --ff-only, confirms the intended deployment, tests the staged release and backs up SQLite before changing the installed application. ArchForge connectivity is required only for fetching new code. A primary VPS outage does not affect the running monitoring service.

./rollback.sh returns the prior code snapshot; it does not reverse database schema migrations. restore.sh restores config and database from a manually selected backup (after explicit confirmation). A daily systemd timer performs a SQLite-consistent backup with 14-day local rotation. This retention period is configurable in scripts/backup.sh.

Monitoring targets

Use TARGET_WEBSITE=https://archforge.nl. The default public API target is an optional, separately monitored service, not a data source required by the monitor. An inaccessible API is reported as an observed failure while VPS 2 remains operational. Leave TARGET_API_URL= blank to disable it.

For real public ArchForge HTTPS checking, configure TARGET_GIT_HTTP_URL to an existing public repository route ending with /info/refs. For example: https://archforge.nl/USER/PUBLIC_REPO.archforge/info/refs if that matches your ArchForge-server URL. The request is read-only and requires a valid ArchForge upload-pack discovery response. Leave empty if your ArchForge HTTPS endpoint is private or unavailable.

ArchForge SSH checks only test TCP plus an SSH protocol banner, not an authenticated ArchForge push. DNS resolution only verifies DNS lookups. A successful HTTPS check does not mean all website features work. Internal components without external endpoints must not be labeled independently healthy.

Configuration

All primary options are documented in .env.example. Modify the real file with:

sudoedit /etc/archforge-status/status.env
sudo systemctl restart archforge-status

For SMTP changes, update /etc/archforge-status/msmtprc as well (owned by archforge-status, mode 600). The app sends mail using Debian's msmtp binary and never relies on VPS 1 SMTP. Discord messages use the standard Discord channel webhook format https://discord.com/api/webhooks/ID/TOKEN, NOT an invite URL such as https://discord.gg/....

Monitoring runs once per minute by default (30-second minimum). The last ~400 days of raw samples are retained. Use the Admin Control Center to publish incident progress and announce planned maintenance. Scheduled maintenance informs visitors, but cannot execute remote maintenance on VPS 1.

Independent security model

The status site listens only on 127.0.0.1:3000; Caddy handles HTTPS.
No shared login tokens with ArchForge, no database credentials from the main platform, no remote shell, no arbitrary URL checking from the admin dashboard.
Public subscriptions are confirmed via email and include unsubscribe links; HTTP forms have CSRF protection and simple rate limits.
Rate limiting is in-process and resets after a service restart; a network-level reverse-proxy limit is recommended for high-traffic installations.
Systemd hardening and per-file permissions are used. Keep Debian, Caddy, Node.js and the service patched.
This is one external monitor on one VPS. If VPS 2 or its network goes down, it cannot independently report its own outage. Consider a third-party heartbeat for that later.

Tests

node --version  # supported in production: v24 or later
npm test
npm run check
bash -n install.sh scripts/*.sh

This is a first release. Run the installer and a controlled failure/recovery test on your VPS before relying on it for production alerts. Never upload real secrets or your SQLite database to ArchForge.