linux_patch_manager/README.md

Linux Patch Manager

Enterprise-class secure web-based management interface for controlling patching and updates on Linux servers and workstations.

Overview

Linux Patch Manager provides a centralized web interface to manage patching and software updates across a fleet of Linux servers and workstations. It communicates with managed devices through the Linux Patch API, leveraging mTLS-secured RESTful endpoints for all operations.

Key Features

• Centralized Dashboard — Monitor patch status across all managed hosts from a single interface
• Multi-Distribution Support — Manage Debian/Ubuntu, RHEL/CentOS/Fedora, Alpine, and Arch hosts
• Secure by Design — mTLS authentication, role-based access control, audit logging
• Batch Operations — Apply patches and updates across multiple hosts simultaneously
• Scheduling — Plan and schedule patch windows with approval workflows
• Reporting — Compliance reporting and patch status dashboards

Architecture

Linux Patch Manager is a web application that acts as a management plane, communicating with the Linux Patch API agent running on each managed host.

┌─────────────────────┐
│  Linux Patch Manager │  ← Web UI (this project)
│   (Management Plane) │
└──────────┬──────────┘
           │  mTLS / REST API
    ┌──────┼──────┐
    ▼      ▼      ▼
┌──────┐┌──────┐┌──────┐
│ Host ││ Host ││ Host │  ← Linux Patch API agents
│  A   ││  B   ││  C   │
└──────┘└──────┘└──────┘

System Requirements

Component	Requirement
Operating System	Ubuntu 22.04 LTS or 24.04 LTS
Database	PostgreSQL 16 (via official PostgreSQL repository)
Memory	2 GB RAM minimum, 4 GB recommended
Storage	1 GB for application + database space
Network	HTTPS access (port 443 recommended)

Installation

1. Download the Package

Download the latest .deb package from the Gitea Releases page:

wget https://gitea-lxc.moon-dragon.us/echo/linux_patch_manager/releases/download/v0.0.2/linux-patch-manager_1.0.0-1_amd64.deb

2. Install PostgreSQL 16

Important: PostgreSQL 16 is NOT available in Ubuntu's default repositories. You MUST add the official PostgreSQL repository.

# Add PostgreSQL official repository
sudo sh -c 'echo "deb http://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/pgdg.list'

# Import signing key
wget --quiet -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo apt-key add -

# Update package list
sudo apt update

# Install PostgreSQL 16 and SSL library
sudo apt install -y postgresql-16 libssl3

3. Install the Package

sudo dpkg -i linux-patch-manager_1.0.0-1_amd64.deb

Or with automatic dependency resolution:

sudo apt install ./linux-patch-manager_1.0.0-1_amd64.deb

Configuration

1. Database Setup

Create the PostgreSQL database and user:

sudo -u postgres psql <<EOF
CREATE DATABASE patch_manager;
CREATE USER patch_manager WITH PASSWORD 'your_secure_password';
GRANT ALL PRIVILEGES ON DATABASE patch_manager TO patch_manager;
\q
EOF

2. Configure the Application

Edit the configuration file:

sudo nano /etc/patch-manager/config.toml

Example configuration:

[database]
url = "postgresql://patch_manager:your_secure_password@localhost/patch_manager"

[server]
host = "0.0.0.0"
port = 8080

[security]
# Generate a secure key for session encryption
session_key = "generate-a-secure-random-key-here"

3. Run Database Migrations

sudo -u postgres psql patch_manager < /usr/share/patch-manager/migrations/001_initial_schema.sql
sudo -u postgres psql patch_manager < /usr/share/patch-manager/migrations/002_seed_admin.sql
sudo -u postgres psql patch_manager < /usr/share/patch-manager/migrations/003_jobs_scheduling.sql
sudo -u postgres psql patch_manager < /usr/share/patch-manager/migrations/004_maintenance_windows.sql
sudo -u postgres psql patch_manager < /usr/share/patch-manager/migrations/005_audit_hardening.sql

Starting Services

Start the Application

sudo systemctl enable --now patch-manager.target

Verify Services are Running

systemctl status patch-manager-web
systemctl status patch-manager-worker

Check Logs

journalctl -u patch-manager-web -f
journalctl -u patch-manager-worker -f

Initial Access

1. Open a web browser and navigate to: https://your-server-ip:8080

2. Default admin credentials (change immediately!):

   • Username: admin
   • Password: Check the migration output or set during setup

3. Complete the initial setup wizard to configure:

   • Admin password change
   • MFA setup
   • First host enrollment

Building from Source

Prerequisites

# Rust toolchain
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

# Node.js 18+
sudo apt install -y nodejs npm

# Build dependencies
sudo apt install -y pkg-config libssl-dev postgresql-16

Build the Package

cd /path/to/linux_patch_manager
chmod +x scripts/build-package.sh
./scripts/build-package.sh

The .deb package will be created in the project root directory.

Documentation

Document	Description
SPEC.md	Full project specification
ARCHITECTURE.md	Architecture and design decisions
REQUIREMENTS.md	Functional and non-functional requirements
docs/security-review.md	Security audit findings
docs/runbooks/restore.md	Disaster recovery procedures

Related Projects

• Linux Patch API — The API agent that runs on each managed host

Troubleshooting

Services Won't Start

# Check configuration syntax
sudo patch-manager-web --validate-config

# Check database connectivity
sudo -u postgres psql -h localhost -U patch_manager patch_manager -c "SELECT 1"

# Check port availability
sudo ss -tlnp | grep 8080

Database Migration Issues

# Check migration status
sudo -u postgres psql patch_manager -c "\dt"

# Re-run specific migration
sudo -u postgres psql patch_manager < /usr/share/patch-manager/migrations/001_initial_schema.sql

License

Private — All rights reserved.

---

Version: 1.0.0-1
Release: v0.0.2
Build Date: 2026-04-28