Maintainarr/README.md

Maintainarr

Maintainarr is a self-hosted Go application for managing a single organization's Linux VM fleet from one dashboard.

It ships with:

• SQLite-backed persistence
• User registration and login
• OTP-based 2FA setup and verification
• Role model with admin, editor, and viewer
• Sidebar dashboard with theme tokens compatible with UI Colors
• VM chip grid with distro icon, CPU/RAM bars, IP, and uptime
• Node overview pages with action buttons and SSH web console
• Wake-on-LAN, restart, shutdown, stat refresh, and apt-upgrade action hooks
• VM groups and recurring/triggered automation job scaffolding
• Go-first backend structure intended for adding more fleet features without rewrites

Branch Model

• main: stable branch
• dev: active feature branch

The repository has been initialized with both main and dev. Work should land in dev first.

Stack

• Go 1.25
• chi router
• modernc.org/sqlite for embedded SQLite
• gorilla/sessions for cookie sessions
• pquerna/otp for TOTP 2FA
• golang.org/x/crypto/ssh for remote command and console transport
• Embedded Go HTML templates plus local static assets

Project Layout

cmd/maintainarr           entrypoint
internal/app              app bootstrap and routing
internal/config           environment configuration
internal/db               sqlite connection and schema bootstrap
internal/handlers         HTTP handlers and websocket console
internal/middleware       auth and role enforcement
internal/models           domain models
internal/services         auth, crypto, nodes, scheduler, repository
internal/views            embedded templates and view helpers
web/static                CSS and browser-side JS

Run

go run ./cmd/maintainarr

Default address: http://localhost:8080

First User

The first registered user becomes the initial admin.

No example users, groups, nodes, or jobs are seeded.

Environment

MAINTAINARR_ADDR=:8080
MAINTAINARR_DB_PATH=data/maintainarr.db
MAINTAINARR_SESSION_KEY=change-me-session-key-please
MAINTAINARR_ENCRYPTION_KEY=change-me-encryption-key-32bytes
MAINTAINARR_ORG_NAME=Maintainarr
MAINTAINARR_BASE_URL=http://localhost:8080
MAINTAINARR_THEME=blue
MAINTAINARR_THEME_MODE=dark
MAINTAINARR_REFRESH_CRON=@every 5s

Roles

• admin: full access, intended for user management and future organization settings
• editor: can operate nodes and create automation jobs
• viewer: read-only access

Theme System

The dashboard is styled around uicolors.app style primary scale variables:

--color-primary-50
--color-primary-100
--color-primary-200
--color-primary-300
--color-primary-400
--color-primary-500
--color-primary-600
--color-primary-700
--color-primary-800
--color-primary-900
--color-primary-950

Replace those values in web/static/css/app.css or feed them through a future admin theme editor to recolor the interface.

Current Scope

This repository now includes the base architecture for:

• auth and sessions
• role-aware route protection
• dashboard rendering
• node actions
• SSH-backed console transport
• SQLite schema for future fleet features
• recurring automation scheduling

Next Expansions

The backend shape is ready for:

• user management screens
• node create/edit flows
• SSH key auth
• richer live metrics collection
• audit logs
• package policy models
• triggered event ingestion
• per-group maintenance windows
• multi-step provisioning workflows