aptacode/rackpeek repository overview

⁠RackPeek

RackPeek is a Web UI & CLI tool for documenting and managing home lab and small-scale IT infrastructure.

It helps you track hardware, services, networks, and their relationships in a clear, scriptable, and reusable way — without enterprise bloat, proprietary lock-in, or drowning in unnecessary metadata and process.

Your data lives in a single human-readable YAML file that you own outright. No database, no telemetry, no ads, no tracking, no artificial restrictions.

RackPeek is open source and community-driven. Code, docs, ideas, bug reports, and real-world usage feedback are all massively appreciated. If you run a home lab, you belong here.

GitHub⁠ · Live Demo⁠ · Docs⁠ · Discord⁠

⁠Quick start

docker volume create rackpeek-config

docker run -d \
  --name rackpeek \
  -p 8080:8080 \
  -v rackpeek-config:/app/config \
  aptacode/rackpeek:latest

Then open http://localhost:8080⁠.

⁠Docker Compose

services:
  rackpeek:
    image: aptacode/rackpeek:latest
    container_name: rackpeek
    ports:
      - "8080:8080"
    volumes:
      - rackpeek-config:/app/config
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-fsS", "http://localhost:8080/health"]
      interval: 30s
      timeout: 5s
      start_period: 15s
      retries: 3

volumes:
  rackpeek-config:

docker compose up -d

A named volume avoids permission issues entirely and is recommended for most users.

⁠Using a bind mount instead

RackPeek runs as a non-root user, UID/GID 1654:1654. A bind-mounted host directory must be writable by that user, or RackPeek cannot create or update your config:

mkdir -p config
sudo chown 1654:1654 config

docker run -d \
  --name rackpeek \
  -p 8080:8080 \
  -v $(pwd)/config:/app/config:Z \
  aptacode/rackpeek:latest

The :Z suffix is required on SELinux-enabled systems (Fedora, RHEL, CentOS) and can be omitted elsewhere.

To confirm the user the container runs as:

docker exec rackpeek id
# uid=1654(app) gid=1654(app)

If you see Access to the path '/app/config/config.yaml' is denied., this is almost always the cause. RackPeek needs to create config.yaml, update it, and write backup files alongside it.

⁠Your data

RackPeek stores all state as YAML under /app/config:

config/
└── config.yaml

Back it up by copying that file, or commit it to git — it is plain text and diffs cleanly. That is the point.

Session keys are persisted under config/.dataprotection on the same volume, so browser logins survive container upgrades.

⁠Configuration

⁠Read-only root filesystem

If you run with read_only: true, also mount a tmpfs for the app's temp directory:

    read_only: true
    tmpfs:
      - /app/tmp:uid=1654,gid=0

⁠The CLI is in the image too

The same image ships the rpk CLI alongside the Web UI, operating on the same config:

docker exec -it rackpeek rpk --help
docker exec -it rackpeek rpk servers add Server1
docker exec -it rackpeek rpk systems list

The Web UI and CLI write to one YAML file without cross-process locking, so treat the UI as the source of truth while it is running.

Full command tree: CLI command reference⁠.

⁠Tags

RackPeek follows Semantic Versioning⁠; the CLI binary and Docker image share the same version number.

⁠Docs

• Overview⁠
• Installation guide⁠
• Inventory API⁠
• Git integration⁠
• Ansible inventory generator⁠
• CLI command reference⁠
• Versioning⁠

Issues and contributions: github.com/Timmoth/RackPeek⁠