The ultimate homelab infrastructure management, automated discovery, and topology mapping engine.
Explore the Docs »

Report Bug · Request Feature

Table of Contents

1. About The Project
   • Built With
   • Core Principles
2. Getting Started
   • Prerequisites
   • Installation
3. Auto-Updates & Zero Data Loss
4. Architecture and RFCs
5. Roadmap
6. License

About The Project

InfraMap is an open-source, homelab-first infrastructure management system. It provides automated device discovery, topology mapping, and a strict "Zero Data Loss" inventory system to help you visualize, track, and manage your entire network and service stack.

Designed specifically for homelabs and small-scale infrastructure, InfraMap integrates seamlessly with providers like Proxmox VE, Docker Engine, UniFi, and SNMP devices to continuously reconcile the state of your network.

Core Principles

• Self-Contained Single Binary (Portainer-Style): The WASM frontend is embedded directly into the Go backend binary (embed.FS). A single process/container serves both the REST/SSE API and the UI.
• Zero Data Loss: Hard deletions are strictly prohibited. Everything is soft-deleted, versioned, and fully auditable.
• Automated Startup Migrations: On container update or restart, pending Goose database migrations execute automatically inside isolated database transactions before serving traffic.
• Resilient Integrations: All external integrations run in isolated contexts with circuit breakers and strict 30-second timeouts. A failing provider will never crash the core engine.

Built With

• Backend: Go (1.22+)
• Database: PostgreSQL (pgx & sqlc for type-safe queries)
• Migrations: Goose (Automated startup migrations)
• Frontend: Kotlin Compose Multiplatform (WASM) embedded via Go embed.FS

Getting Started

InfraMap is fully self-contained. A single command spins up the database, automatically applies migrations, and launches the unified backend and embedded frontend.

Prerequisites

• Docker & Docker Compose
• Go 1.22+
• Make

Installation

1. Clone the repo:

   git clone https://github.com/matheussouza/inframap.git
   cd inframap

2. Run the single self-contained development environment:

   make dev

3. Open http://localhost:8055 in your browser (configurable via INFRAMAP_PORT).

Auto-Updates & Zero Data Loss

InfraMap is designed for zero-friction homelab maintenance. You can safely configure auto-updater agents like Watchtower or run docker compose pull on the :latest tag:

• Automatic Schema Upgrades: Upon container restart with a newer version, InfraMap automatically executes any pending Goose database migrations before opening network ports.
• Transaction Safety & Rollbacks: Every migration runs inside a PostgreSQL transaction. If a migration fails, the transaction rolls back cleanly, preventing data corruption and keeping your existing database intact.
• Backward Compatibility: Database schema changes strictly follow additive (Expand-Contract) patterns. Updates will never drop data or break historical records.

Architecture and RFCs

Every major architectural decision, data model, and API contract is extensively documented in our RFCs. Before contributing, please review the foundational guidelines:

• RFC-001: Technology Stack
• RFC-005: Architecture
• RFC-006: Data Model
• RFC-009: Integration SDK & Event Bus
• RFC-010: Repository Scaffolding

See the docs/ folder for the full list of RFCs.

Roadmap

The project is currently moving from the Foundation phase to the Scaffolding phase.

See the ROADMAP.md file for a complete list of upcoming features, modules, and integrations.

License

Distributed under the Apache License 2.0. See LICENSE for more information.

(back to top)