InventoryLite

Self-hosted live inventory management for servers and machines

---

Overview

InventoryLite is a self-hosted inventory system that collects real-time metrics from your machines via lightweight agents. Agents are written in pure bash (Linux) or PowerShell (Windows) with zero runtime dependencies on the monitored machine.

No pip. No compiled binaries. No agent framework. Just a shell script and curl.

---

How It Works

Each agent sends a signed heartbeat every 30 seconds containing CPU, RAM, disk, uptime, IP, MAC, OS and hostname. The server verifies the HMAC-SHA256 signature, stores the data in PostgreSQL, and surfaces it in a live web dashboard.

---

Deployment

curl -fsSL https://raw.githubusercontent.com/patgames36/inventorylite/main/docker-compose.yml -o docker-compose.yml
curl -fsSL https://raw.githubusercontent.com/patgames36/inventorylite/main/.env.example -o .env

nano .env   # set SERVER_HOST and passwords

docker compose up -d

Open http://YOUR_SERVER_IP:8000 and sign in with the credentials from your .env.

---

Adding a Machine

1. Web UI — Agents tab — New Agent
2. Enter a name and select the target OS
3. Run the generated command on the target machine

Linux

curl -fsSL http://YOUR_SERVER:8000/install/KEYPAIR_ID | sudo bash
systemctl start agentlite && systemctl enable agentlite

Windows (admin PowerShell)

Invoke-Expression (Invoke-WebRequest -Uri http://YOUR_SERVER:8000/install/KEYPAIR_ID/windows -UseBasicParsing).Content

The agent registers itself on first heartbeat and appears online in the dashboard within 30 seconds.

---

Agent Requirements

Platform	Requirements
Linux	bash, curl, openssl — present on every distro by default
Windows	PowerShell 5.1 — built into Windows 10 and Server 2016

---

Metrics Collected

Field	Description
hostname	Machine hostname
ip	Outbound IP address
mac_address	Primary interface MAC address
os_version	OS name and version string
uptime_seconds	Seconds since last boot
cpu_percent	CPU usage averaged over 1 second
ram_total_gb / ram_used_gb	Total and used RAM
storage_total_gb / storage_free_gb	Disk size and free space
last_ping_ms	TCP round-trip latency to server

---

Configuration

Variable	Default	Description
SERVER_HOST	http://localhost:8000	Public URL that agents send heartbeats to
DATABASE_URL	postgresql://agentlite:agentlite@db/agentlite	PostgreSQL connection string
POSTGRES_PASSWORD	agentlite	Database password
ADMIN_USERNAME	admin	Initial web UI username
ADMIN_PASSWORD	admin	Initial web UI password
SESSION_TTL_HOURS	24	Web UI session duration in hours

ADMIN_USERNAME and ADMIN_PASSWORD only apply on first boot when the database is initialized. Set them before running docker compose up for the first time.

---

Compose Files

File	Purpose
docker-compose.yml	Production — pulls pre-built image from Docker Hub
docker-compose.dev.yml	Development — builds from source with live reload
docker-compose.build.yml	Maintainers — builds and pushes image to Docker Hub

---

Building from Source

git clone https://gitlab.patserver.com/patrick19368/inventorylite.git
cd inventorylite
cp .env.example .env && nano .env
docker compose -f docker-compose.dev.yml up --build

---

Publishing a New Image

docker login
docker build -t patgames36/inventorylite:latest -t patgames36/inventorylite:1.0.0 .
docker push patgames36/inventorylite:latest
docker push patgames36/inventorylite:1.0.0

Update a running server without touching the database:

docker compose pull server
docker compose up -d --force-recreate server

---

Project Structure

inventorylite/
├── server/
│   ├── agents/
│   │   ├── agentlite-linux.sh        # Bash heartbeat agent
│   │   └── agentlite-windows.ps1     # PowerShell heartbeat agent
│   ├── config/settings.py            # Environment configuration
│   ├── db/database.py                # Connection pool and schema
│   ├── middleware/auth.py            # Session management
│   ├── models/schemas.py             # Request and response models
│   ├── routes/
│   │   ├── agents.py                 # Agent CRUD endpoints
│   │   ├── auth.py                   # Login and logout
│   │   ├── heartbeat.py              # Receive and verify heartbeats
│   │   └── install.py                # Generate installer scripts
│   └── main.py
├── webui/
│   ├── index.html
│   └── static/
│       ├── css/style.css
│       └── js/app.js
├── Dockerfile
├── .dockerignore
├── docker-compose.yml
├── docker-compose.dev.yml
├── docker-compose.build.yml
└── .env.example

---

License

MIT