PortNote

A focused review of the MIT-licensed port documentation tool. No dashboard bloat, no uptime graphs — just the answer to “which service was on port 3001 again?”

---

TL;DR

• What it is: A self-hosted web app for documenting and tracking port usage across servers and VMs — not a full dashboard, not a monitoring tool, just a clean interface for the “what’s running where” problem [README].
• Who it’s for: Homelab runners, self-hosters, and DevOps engineers managing multiple Docker hosts or Proxmox VMs who’ve graduated from the “let me check my notes” phase [1].
• Cost savings: There is no SaaS version to escape from. PortNote is MIT-licensed, free, and runs on whatever server you already have. The only cost is a slice of VPS RAM [README].
• Key strength: Focused scope. It does one thing — port documentation — and does it cleanly, including an automatic port scanner that builds the initial list for you [1].
• Key weakness: Single-contributor project with 1,247 GitHub stars and limited third-party coverage. If the developer moves on, you’re maintaining a Next.js app. Also, it’s a documentation tool, not a monitoring tool — it won’t tell you if a service goes down [README][1].

---

What is PortNote

PortNote is a web-based port registry. You deploy it, point it at your servers, and it gives you a structured, editable interface for documenting which service is running on which port across which machine. That’s the entire scope, and it’s intentionally that narrow.

The README pitch is blunt and accurate: “Stop juggling spreadsheets and guessing which service uses which port.” If you’ve managed more than five Docker containers across two hosts, you’ve felt this problem. Port 8080 is… Traefik? Or was that 8090? Portainer is on 9000 but which one — the management UI or the agent? PortNote is the answer to that question [README][1].

The project was built by Damian (crocofied on GitHub), who also maintains CoreControl, a broader infrastructure management tool. PortNote is the narrower sibling: no graphs, no alerts, no integrations. Just ports. It sits at 1,247 GitHub stars with 32 forks and one contributor as of this review, with three releases — the latest being v1.2.0, published May 14, 2025 [README].

The stack is Next.js + TypeScript for the frontend, PostgreSQL + Prisma ORM for storage, and a separate Go-based agent container that handles the actual port scanning. The UI is built with Tailwind CSS and DaisyUI. Docker Compose deployment [README].

---

Why People Choose It

The XDA Developers review by Dhruv Bhutani — the only full-length third-party article on PortNote at the time of this writing — opens by describing the exact problem the tool solves: “What ports are actually in use? Which app was running on port 3001? Or what port was Portainer running on? If you’re like me, and you’ve gone down the Docker rabbit hole, the maze of IPs, ports, and service names across a dozen containers quickly becomes a tangle you’d rather avoid” [1].

The review is enthusiastic: Bhutani calls PortNote “the first app I install on every server I manage,” which is a credibility signal worth noting — that’s the kind of statement people make about tools like Portainer or Caddy, not about port trackers [1].

Three things come through consistently in the coverage:

The automatic port scanner removes the cold-start problem. The most annoying part of any documentation tool is populating it from scratch. PortNote’s agent scans existing port usage and presents it in an editable format, so you’re not manually typing in 40 entries on day one. Bhutani notes: “The automatic port scanner immediately scans all ports being used and lays out in an easy-to-edit manner” [1].

Setup is genuinely fast. The standard complaint about self-hosted tools is that “simple” in the README translates to two hours of troubleshooting. PortNote appears to be an exception. The XDA review calls it “a few minutes to get up and running” and notes it “doesn’t need any extensive work with environment variables” [1]. The docker-compose file is eight environment variables, all obvious.

It doesn’t try to be more than it is. The review explicitly praises the scope: “It doesn’t try to be another full-fledged dashboard like Portainer or Dashy. Nor does it give you granular information on things like uptime. Instead, it focuses on one thing.” In a category crowded with tools that add features until they become Grafana with worse UX, this is worth something [1].

The mariushosting.com community, which publishes NAS setup guides for Synology and UGREEN hardware, also covered PortNote with a deployment walkthrough — a signal that the tool has reached the NAS homelab audience, not just the Linux-on-a-VPS crowd [2].

---

Features

Based on the README, screenshots, and the XDA review:

Core functionality:

• Web interface for adding and documenting servers, VMs, and containers [README]
• Per-entry fields: name, port number, notes, icon, category, metadata [1]
• Automatic port scanner via the separate agent container — scans running ports and pre-populates the list [1][README]
• Random port generator — picks an available port when you’re spinning up a new service and don’t want to collide with anything [README]
• Full CRUD: create, edit, organize, delete entries [README]

Infrastructure:

• PostgreSQL database via Prisma ORM — data persists across restarts and is queryable [README]
• REST API listed as a canonical feature in the merged profile, though documentation on the API surface is limited [merged profile]
• Separate agent container (written in Go) handles port scanning independently from the web UI [README]
• Multi-server support — you can add multiple hosts, not just the one PortNote runs on [README][1]

Access control:

• Single-user authentication via username/password set in environment variables [README]
• JWT-based session management [README]
• No multi-user support, no RBAC, no SSO — this is single-owner software [README]

What it explicitly does not do: uptime monitoring, service health checks, alerting, reverse proxy management, container lifecycle control. If you want those, you want Portainer, Uptime Kuma, or Dashy alongside it — not instead of it [1].

---

Pricing: SaaS vs Self-Hosted Math

There is no SaaS version of PortNote. The comparison here is not “cloud plan vs self-hosted” but “PortNote vs the status quo.”

PortNote self-hosted:

• Software: $0 (MIT license) [README]
• Hosting: whatever slice of the server you’re already running. The compose file adds a PostgreSQL instance and a Go agent alongside the Next.js app. On a machine already running Docker, the incremental resource cost is modest.
• If you need a dedicated VPS for it: $4–6/mo on Hetzner or Contabo. But almost nobody will deploy PortNote on its own VPS — it runs alongside everything else it’s tracking.

The alternative you’re replacing:

• A Notion database: $0 for personal use but lives in a third-party SaaS and doesn’t auto-populate from port scans.
• A spreadsheet: $0 but zero discoverability, no scan integration, manual everything.
• Memory and SSH: $0 and $0 in reliability.
• A commercial CMDB or IPAM tool: $50–200+/mo for enterprise software that does far more than you need.

For homelab runners and small ops teams, PortNote replaces a workflow that costs nothing but time and mental overhead. The ROI calculation is time saved, not dollars saved — which is honest, and the right frame for a tool at this scope.

---

Deployment Reality Check

The install path is Docker Compose with three containers: the web app, the agent, and PostgreSQL. The README includes the complete compose file — no hunting through documentation for the right image or environment variable names [README].

Required environment variables:

• JWT_SECRET — any random string
• USER_SECRET — any random string
• LOGIN_USERNAME / LOGIN_PASSWORD — your credentials
• DATABASE_URL — the connection string to the bundled PostgreSQL

That’s it. No SMTP required. No OAuth setup. No external services.

What you actually need:

• Docker and docker-compose on a Linux host
• A port (3000 by default) exposed, with a reverse proxy if you want HTTPS
• Persistent volume for PostgreSQL data (included in the compose file)

What the XDA review says about setup: “It literally takes a few minutes to get up and running and doesn’t need any extensive work with environment variables” [1]. That matches the compose file complexity — it’s genuinely short.

Realistic gotchas:

• Single-user only. If you want two people to manage ports on a shared homelab, you’ll hit the architectural ceiling immediately — there’s no multi-user model.
• The agent container scans ports on the host where it runs. If you’re documenting ports across multiple servers, you add them manually or run the agent on each host. The compose file doesn’t suggest a multi-host agent architecture.
• No HTTPS out of the box — you’ll want Caddy or nginx in front for anything beyond local network access.
• The project has one contributor. This isn’t a criticism of the code quality, but it’s a risk factor for long-term maintenance. Check the commit history before betting a production ops workflow on it.
• Three releases total (v1.0 through v1.2.0) — this is early-stage software. Features may change, APIs may shift.

Time estimate for a technical user: 10–20 minutes from zero to working instance. For a non-technical founder following the compose file literally: 30–60 minutes including reverse proxy setup.

---

Pros and Cons

Pros

• Focused scope that actually works. PortNote doesn’t try to replace your monitoring stack, your dashboard, or your CMDB. It solves one problem and solves it well [1].
• Automatic port scanner removes setup friction. New installs get a pre-populated list from the agent scan instead of starting from a blank slate [1].
• MIT-licensed. Fork it, modify it, run it on air-gapped infrastructure — no strings [README].
• Minimal dependencies. Three Docker containers, five environment variables. One of the cleaner compose files in the self-hosted category [README].
• NAS-compatible. Mariushosting coverage confirms Synology and UGREEN NAS deployment works without hacks [2].
• Random port generator. Small feature, but actually useful when spinning up service number 47 and you’ve lost track of what’s taken [README].
• Clean UI. DaisyUI/Tailwind stack produces a consistent, readable interface. The screenshots show a layout that doesn’t try to cram everything into one screen [README][1].

Cons

• Single contributor, early-stage project. 86 commits, 3 releases, 1 developer. This is the risk profile of software you should be prepared to maintain yourself if crocofied moves on [README].
• No multi-user support. Username and password are set in environment variables. There’s no invite system, no roles, no separation between admin and read-only access [README].
• Documentation is thin. The README covers deployment. Everything else — the REST API, the agent protocol, configuration edge cases — is left to reading the source [merged profile].
• Limited third-party coverage. At the time of this review, one full-length article exists (XDA Developers). That’s a useful data point about project maturity and adoption [1].
• No alerting or health checks. PortNote documents ports; it doesn’t monitor the services on them. You need a separate tool (Uptime Kuma, Healthchecks.io) for availability monitoring [1].
• Agent architecture is opaque. The Go agent handles port scanning, but the README doesn’t document how it discovers ports on remote hosts vs. local, or how frequently it rescans [README].
• No data export. PostgreSQL is the backend, so you can dump the database directly, but there’s no built-in export to CSV or JSON from the UI. If you want portability, you’re writing SQL [README].

---

Who Should Use This / Who Shouldn’t

Use PortNote if:

• You manage more than 10 Docker containers across multiple hosts and you’ve lost track of what’s on what port.
• You’re running a homelab on Proxmox, Synology, or UGREEN NAS and want a clean web interface instead of a mental map or a Notion doc.
• You want to stop the “SSH in and check which ports are in use” workflow.
• You’re comfortable deploying a Docker Compose file and setting up a reverse proxy.
• You want MIT-licensed software you can run indefinitely without a vendor relationship.

Skip it if:

• You need multi-user access control. PortNote is single-user by design.
• You need uptime monitoring alongside port documentation — you’ll need a second tool anyway, and a dashboard like Dashy or Homarr already handles both with more features.
• You’re a team of more than 2-3 people who all need to edit the port registry. The auth model doesn’t support this.
• You’re risk-averse about single-contributor open-source tools in a production environment.
• You need a documented REST API for integration with other systems — the API exists but isn’t formally documented [merged profile].

---

Alternatives Worth Considering

PortNote operates in a narrow niche, and direct alternatives are sparse:

• Dashy — A self-hosted dashboard with service organization, icons, and categories. Much broader scope than PortNote — it’s a bookmarks/links dashboard, not a port registry — but if you want “at a glance” visibility without port-level documentation, Dashy may be enough.
• Homer — Another self-hosted dashboard. Configured via YAML, no automatic scanning, no port-level notes. Simpler than Dashy, more manual than PortNote.
• Portainer — Full Docker management platform. Knows about every container and its exposed ports, but the UI is oriented toward container management, not documentation. No notes, no categories, no “why is this on port 8093” metadata.
• Homarr — A dashboard with Docker integration, service tiles, and network information. Closer to PortNote’s territory than Dashy, but still more dashboard than registry.
• A Notion or Obsidian database — Genuinely viable for small setups. No auto-scanning, no dedicated UI, but portable and no additional infrastructure to run.
• NetBox — The enterprise answer to this problem. Full IPAM (IP Address Management) with VLANs, prefixes, devices, services, and a complete REST API. Massively more powerful and massively more complex to deploy. If your port chaos reaches the scale where PortNote feels inadequate, NetBox is the next rung up.

For most homelab runners, the realistic choice is PortNote vs. nothing. If PortNote’s single-contributor risk is a concern and you need something more established, NetBox is the alternative — but it’s a very different scale of tool.

---

Bottom Line

PortNote solves a real, specific problem that most homelab tooling ignores entirely. Port documentation sounds boring until you’re SSH’d into a server at 11pm trying to remember which port your monitoring stack is on. The automatic port scanner, clean interface, and five-minute Docker setup make it the easiest answer to that problem in the self-hosted space right now.

The caveats are real: one contributor, three releases, thin documentation, no multi-user support. This is early-stage homelab software, not production CMDB. If you’re running a solo or small-team homelab and your port inventory lives in a spreadsheet or your head, PortNote is worth the 20-minute install. If you need team access, audit history, or enterprise-grade reliability, look at NetBox instead.

For everyone else: it’s free, it’s MIT, it takes 20 minutes to deploy, and it does exactly what it says.

---

Sources

1. Dhruv Bhutani, XDA Developers — “3 reasons why PortNote is my port of call on every server” (May 28, 2025). https://www.xda-developers.com/reasons-why-portnote-port-of-call-on-every-server/
2. Marius Hosting — “How to Install PortNote on Your UGREEN NAS”. https://mariushosting.com/page/118/

Primary sources:

• GitHub repository and README: https://github.com/crocofied/PortNote (1,247 stars, MIT license, 1 contributor)
• Docker Hub image: haedlessdev/portnote:latest
• Latest release: v1.2.0 (May 14, 2025)