infmap/README.md

infmap - Infrastructure Map

A Dropshell template that provides a web dashboard showing the status of your servers. It SSHes into configured servers periodically to collect system information and displays it in an attractive dark-themed web UI.

What It Collects

• System: hostname, OS, kernel, architecture, uptime
• Hardware: motherboard make/model/version, BIOS version/date
• CPU: model, cores, sockets, threads, live usage %
• Memory: total, used, available, live usage %
• Storage: physical disks, mounted filesystems with usage %
• GPUs: all detected graphics/3D/display adapters
• Network: all interfaces with IPv4/IPv6, MAC, state, speed, driver
• Routing: default gateway and interface
• DNS: configured nameservers
• Temperatures: CPU/chipset temps via lm-sensors or thermal zones
• Tailscale: IP and hostname (if installed)

All information is gathered without root access using /sys/class/dmi/id/, lscpu, /proc/meminfo, lspci, ip addr, sensors, etc.

Architecture

Single Docker container running a Python Flask app:

• Collector thread: SSHes into servers on a schedule, runs a gather script, stores results in SQLite
• Web server: Serves the dashboard on a configurable HTTP port

Data is persisted in a Docker volume (${CONTAINER_NAME}_data).

Setup

1. Create the service

dropshell create-service <server> infmap <service-name>

2. Configure

Edit service.env:

Variable	Default	Description
CONTAINER_NAME	infmap	Docker container/project name
SSH_USER	root	Dropshell SSH user for this service
WEB_PORT	8080	HTTP port for the web dashboard
SSH_KEY_PATH	/root/.ssh/id_ed25519	Host path to SSH private key for connecting to monitored servers
COLLECTION_INTERVAL	300	Seconds between collection runs
MAX_CONCURRENT_SSH	5	Max simultaneous SSH connections

Edit infrastructure.conf to define your servers:

Production
  prod-web-01 https://web01.example.com
  prod-db-01
  prod-app-01 https://app01.example.com:8080

Development
  dev-01
  dev-02
  admin@legacy-server

• Group names are freeform labels (no indentation)
• Servers are indented with HOSTNAME, USERNAME@HOSTNAME, or either followed by a URL
• Username defaults to infmap if not specified
• An optional URL after the host adds a clickable link on the dashboard
• Lines starting with # are comments

3. Setup remote servers

Run the setup script on each server you want to monitor. It creates a locked-down infmap user, installs your public key with SSH restrictions, and installs dependencies (lm-sensors, pciutils, etc.):

curl -fsSL https://getbin.xyz/infmap-setup | bash

To use a custom public key URL instead of the default (https://getbin.xyz/infmap-pub):

curl -fsSL https://getbin.xyz/infmap-setup | bash -s https://example.com/my-key.pub

The script:

• Creates an infmap user with no password (locked)
• Installs the SSH key restricted to bash -s only (no shell, no forwarding)
• Disables password auth for the user via sshd Match block
• Installs lm-sensors, pciutils, iproute2 for full data collection
• Supports Debian/Ubuntu, Alpine, and OpenWrt

4. Install

dropshell install <server> <service-name>

The dashboard will be available at http://<server>:<WEB_PORT>.

Web Dashboard

• Servers displayed in cards grouped by group name, sorted by primary IP
• Each card shows hostname, IP, OS, and color-coded usage bars for CPU, RAM, and disk
  • Green: < 60%
  • Yellow: 60-75%
  • Orange: 75-90%
  • Red: > 90%
• Click a card to expand full hardware and network details
• Page auto-refreshes every 60 seconds

API

• GET / - Web dashboard
• GET /api/servers - JSON array of all servers with full details