Version: v0.4.12
SimpleLinuxUpdater is a self-hosted web UI that helps you manage apt updates on Debian-based servers over SSH. It provides an approval workflow, health checks, audit history, and basic observability so you can update hosts confidently without logging into each machine.
SimpleLinuxUpdater is designed for trusted environments (LAN/VPN). It connects to your servers via SSH and runs apt operations directly for root SSH sessions or with sudo for non-root users. Updates are gated behind pending_approval, and the UI surfaces checks, logs, and audit events.
- Multi-server management (custom SSH ports supported)
- Enable or disable servers from Manage Servers. Disabling preserves credentials and history while blocking manual maintenance, scheduled runs, and automatic host-facts refreshes. Finish or cancel any active operation before disabling a server; re-enable it to resume normal scheduling.
apt update+ pending package listing, gated behind approval- Four explicit approval scopes: standard updates, standard security updates, kept-back security updates, or a full upgrade with package-removal confirmation
- Approval bound to the displayed job and plan generation, revalidation before execution, and APT enforcement when removals are not approved
- Distribution-verified CVE assessment for Debian 12/13 and Ubuntu 22.04/24.04/26.04, with fixes and remaining exposure shown separately
- Baseline and plan-aware disk/APT pre-checks before approval, including exact simulated size facts with a conservative fallback, plus post-update health checks
- Durable APT reconciliation and guided repair after uncertain package-manager outcomes
- Controlled reboot with SSH recovery, uptime reset, and reboot-required verification
- Per-server Recommended action guidance on Status and immediate eligibility-aware bulk actions
- Scheduled policies with dry-run previews, maintenance windows, and success-gated canary/wave rollouts
- Generic webhook, Discord, and Telegram notifications with delivery diagnostics
- On-demand
apt autoremove - Activity history (audit trail) stored in SQLite
- Observability:
/observabilitydashboard and PrometheusGET /metrics - Built-in single-user login with first-run setup, Argon2id password hashing, and SQLite-backed sessions
- In-app encrypted backup/restore (DB + config, optional
known_hosts) for host/container migration
cp .env-template .env
docker pull ghcr.io/nolife141-teams/simplelinuxupdater:v0.4.12
docker run --env-file .env -p 8080:8080 -v debian-updater-data:/data ghcr.io/nolife141-teams/simplelinuxupdater:v0.4.12Open http://localhost:8080.
On first run, you will be redirected to /setup to create the local admin account.
After setup, sign in at /login.
The container image explicitly sets DEBIAN_UPDATER_LISTEN_ADDR=:8080 so its
published port remains reachable. A directly launched binary defaults to
127.0.0.1:8080; set DEBIAN_UPDATER_LISTEN_ADDR only when another bind address
is required. If first-run setup is exposed beyond loopback, limit access to the
intended LAN, VPN, or authenticated reverse proxy rather than the public internet.
For Prometheus, configure your scraper with:
Authorization: Bearer <token-created-in-admin-page>
Metrics token flow:
/metricsis disabled by default.- Sign in, go to
/admin, then generate or rotate the Metrics API token. - The token is shown once. Store it in your scraper secret manager.
Backup/restore flow:
- Sign in and open
/admin-> Backup & Restore. - Export creates one encrypted backup file (
.slubkp) containing:servers.dbconfig.json- optional
known_hosts(toggle at export time)
- Restore applies immediately (no restart required), replaces
servers.dband optionalknown_hosts, validates backupconfig.json, and re-encrypts restored secrets with the localconfig.jsonkey. - Verify the downloaded archive in Admin before restore; verification checks the manifest and decryptability without changing application state.
- The backup passphrase is not stored by the app; keep it in your secret manager.
Environment variables for auth/session:
DEBIAN_UPDATER_SESSION_COOKIE_SECURE: optional boolean (true|false, defaultfalse), enables secure-only session cookies; settruebehind HTTPS.DEBIAN_UPDATER_SESSION_IDLE_TIMEOUT_HOURS: optional integer idle timeout in hours;0or unset keeps default behavior.
Environment variables for job logs:
DEBIAN_UPDATER_JOB_LOG_RETENTION_DAYS: completed-job log retention in days (default30, allowed1..3650). Expiration removes detailed log content while preserving job status, summary, metadata, and timestamps.DEBIAN_UPDATER_JOB_LOG_MAX_BYTES: maximum detailed log bytes persisted per job (default2097152, allowed131072..1073741824). Oversized logs retain their first 64 KiB and newest output with an explicit truncation marker.
In-memory SSH diagnostics retain at most 256 KiB per stream plus a truncation marker; the live status log retains 32 KiB. Read-only output that must be parsed completely fails explicitly above 4 MiB per stream. These limits do not reduce the configured persisted job-log limit.
Environment variable for host facts:
DEBIAN_UPDATER_HOST_FACTS_AUTO_REFRESH_ENABLED: optional boolean (true|false, defaulttrue) controlling the periodic sequential refresh worker. Successful updates, controlled reboots, and scheduled scans continue to refresh facts when the worker is disabled.
Programmatic auth note:
POST /api/auth/setup,POST /api/auth/login, andPOST /api/auth/logoutrequire same-origin host checks:- At least one of
OriginorReferermust be present - Any provided
Origin/Refererhost must match request host Sec-Fetch-Site: same-originis recommended and validated when present
- At least one of
Download the archive for your platform from GitHub Releases and run the included webserver binary. Release archives include templates/, static/, and .env-template.
Example (Linux amd64):
VERSION="0.4.12"
APP="SimpleLinuxUpdater_${VERSION}"
ARCHIVE="${APP}_linux_amd64.tar.gz"
curl -L -o "${ARCHIVE}" "https://github.com/NoLife141-Teams/SimpleLinuxUpdater/releases/download/v${VERSION}/${ARCHIVE}"
tar -xzf "${ARCHIVE}"
cd "${APP}"
./webserverFor binary releases, export environment variables in your shell before starting ./webserver; .env files are only consumed when you pass them to Docker with --env-file.
- Documentation map
- Installation
- Configuration
- Usage
- Deployment
- Security
- Troubleshooting
- Release smoke checklist
- Computer Use release checklist
- Production manual QA checklist
- Architecture
- Contributing
Choosing between SimpleLinuxUpdater, scripts, and Ansible: see docs/usage.md.
This project can run apt commands via sudo on remote hosts and stores SSH credentials encrypted in SQLite. Do not expose the UI to the public internet. See docs/security.md.
Frontend CSP policy:
- UI pages run with strict CSP (
script-src 'self',style-src 'self' https://fonts.googleapis.com,font-src 'self' https://fonts.gstatic.com). - Inline
<script>, inline<style>, inlineon*=handlers, and inlinestyle=attributes are prohibited. - CI tests fail if these inline patterns are reintroduced in the main UI templates.
- For local Codex in-app-browser testing only, set
DEBIAN_UPDATER_DEV_ALLOW_BROWSER_ANNOTATIONS=truebefore startup. This permits injected inline<style>elements throughstyle-src-elem; scripts and the default production policy remain strict. Do not enable it on a remotely exposed deployment.
See docs/contributing.md.
If you have a Linux server, a homelab, or a small fleet of Debian/Ubuntu machines, your feedback and real-world testing is exactly what this project needs.
Ways you can help:
- Tell me what you want the tool to do next (feature requests and priorities)
- Report bugs with a short description and the relevant logs
- Share what hardware/OS you run (Debian/Ubuntu versions, VPS vs homelab) and what worked or did not
- Suggest safer defaults for checks, approvals, and retries
- Review the UI flow and propose improvements that reduce operational mistakes
MIT. See LICENSE.