# 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](https://uicolors.app/generate)
- 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

```text
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

```powershell
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

```env
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:

```css
--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
