This is where PortNote comes in — a minimal, beautiful, and self-hosted tool to help you track and document all your used ports in one glance.

Whether you’re running dozens of Docker containers, VMs, or bare-metal services, PortNote is a must-have for keeping your infrastructure tidy and your sanity intact.

What is PortNote?

PortNote is a web-based app designed to let you quickly and visually document port usages. Think of it as a personal notepad or dashboard specifically built for network and application ports.

It’s completely self-hosted, requires no external services, and offers a beautiful interface for you to:

• Track which services use which ports
• Add meaningful descriptions and links
• Group entries by server or IP
• Avoid port conflicts
• Stay organized, especially in a growing homelab or VPS setup

PortNote is perfect for:

• Homelab enthusiasts
• Sysadmins managing multiple services
• Developers juggling local development ports
• Anyone using Docker, Proxmox, or VMs

Key Features

• Visual port mapping: Clean, card-style display of services and ports
• Notes and descriptions: Add context to each port so you never forget
• Clickable links: Link to service dashboards or local UIs
• Group by server/IP: Useful when managing multiple machines
• Lightweight & fast: No database, runs entirely in your browser
• Simple JSON backend: Data is stored in a local db.json file
• Docker-ready: Just one container to deploy

How to Deploy PortNote (Docker)

Getting PortNote running is super simple. Here’s a quick guide to deploy it using Docker:

Step 1: Clone the Repository

git clone https://github.com/crocofied/PortNote.git
cd PortNote

Step 2: Launch with Docker

docker compose up -d

That’s it!

By default, PortNote runs on port 5173. Open your browser and head to:

http://localhost:5173

You’ll be greeted with a clean and modern interface where you can begin adding your services and their associated ports.

Data Storage

PortNote stores your port notes in a local file called db.json.

By default, this file is mounted into the container to persist your data:

volumes:
  - ./db.json:/app/db.json

You can easily back it up, version it with Git, or sync it across devices if needed. It’s that simple.

How to Use PortNote

Once you’re inside the web UI, you’ll see a form to add a new port entry. Here’s how you might use it:

Click Add, and the port is logged and visually displayed on your dashboard.

You can edit or delete entries anytime — it’s designed to be fast and intuitive.

Demo

Want to try before hosting?

A live demo is available at:
https://portnote-demo.netlify.app

Note: The demo does not save your data between sessions.

Privacy and Simplicity

PortNote doesn’t phone home. It’s a fully static app with no telemetry, no analytics, and no dependencies beyond your browser and the JSON file. It’s perfect for privacy-focused users.

In fact, if you’d prefer to run it without Docker, you can even build and serve it statically via NGINX, Caddy, or any file server.

Advanced Deployment (Static Hosting)

Want to host PortNote without Docker? You can!

Build it manually:

npm install
npm run build

Then copy the contents of the dist/ directory to any web server of your choice — it’s just HTML, CSS, and JS.

You’ll also need to configure access to db.json or wire it up to a backend of your choice (e.g., Firebase, Supabase, etc.) if you want something more advanced.

Why PortNote is Useful

In a world where we’re running Grafana on :3000, Portainer on :9000, Prometheus on :9090, your blog on :4000, and who knows what else — it’s easy to forget.

PortNote gives you a single place to document everything and avoid confusion or port conflicts.

It also becomes handy when you revisit your homelab setup after a few weeks (or months) and don’t want to reverse-engineer every docker-compose.yml.

Final Thoughts

PortNote is one of those tools that’s small, but incredibly effective. If you maintain any sort of local or cloud infrastructure, this is a fantastic addition to your toolbox.

No overhead, no login systems, no complex config. Just a clean interface to help you stay organized.

Official GitHub:
https://github.com/crocofied/PortNote

Created by: @crocofied

The post PortNote – A Beautiful and Simple Way to Document Your Network Ports appeared on Hamradio.my - Amateur Radio, Tech Insights and Product Reviews by 9M2PJU.