PortNote – A Beautiful and Simple Way to Document Your Network Ports

When you run a self-hosted home lab or manage multiple services on a single machine, it’s easy to lose track of what port is used by what service. You open :3000 and wonder — is that Grafana or some test app you forgot about last year?

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