The open source tool for visualizing and organizing port usage gets a major upgrade with automatic detection, smarter port generation, and Docker deployment updates.
The developer behind CoreControl has just released version v1.1.0 of PortNote, a lightweight, self-hosting-friendly tool designed to give you full visibility and control over port usage across your infrastructure. Just one day after the previous release, the developer has implemented key user feedback—proving once again how responsive the open source community can be.
“Each self-hosted setup is unique. You may not need it, but for others, it saves a lot of time,” the author noted in response to comments from users who prefer manual scripts or CLI tools.
What is PortNote?
PortNote is a clean and intuitive web interface that lets you:
- See which ports are in use and what services are using them.
- Document port assignments to avoid future conflicts.
- Generate new, unused ports automatically.
- Add and manage servers and virtual machines with ease.
It’s built for sysadmins, homelab enthusiasts, and devops engineers who want to bring order to one of the most overlooked parts of server management.
What’s new in PortNote v1.1.0?
This release introduces several powerful features and quality-of-life improvements:
🔍 Auto Port Detection
With a single click, you can now scan your server and detect all currently used ports. No more manual input—this feature significantly streamlines the initial setup process.
⚙️ Smart Port Generator
The built-in port generator now only suggests ports that are not already in use, making it safer and faster to deploy new services.
🧩 UI Enhancements
- A new footer with version info.
- Improved port badges for better visual clarity.
🐞 Bug Fixes
- Fixed an issue where deleting ports didn’t work correctly.
- Fixed a bug where servers disappeared when edited as VMs of other servers.
🐳 Important: Docker Compose Changes
The new port scanning capability requires an additional container: portnote-agent. If you’re updating from a previous version, make sure to adjust your Docker Compose setup accordingly.
services:
web:
image: haedlessdev/portnote:latest
ports:
- "3000:3000"
environment:
JWT_SECRET: RANDOM_SECRET
USER_SECRET: RANDOM_SECRET
LOGIN_USERNAME: username
LOGIN_PASSWORD: mypassword
DATABASE_URL: "postgresql://postgres:postgres@db:5432/postgres"
agent:
image: haedlessdev/portnote-agent:latest
environment:
DATABASE_URL: "postgresql://postgres:postgres@db:5432/postgres"
db:
image: postgres:17
restart: always
environment:
POSTGRES_USER: postgres
POSTGRES_PASSWORD: postgres
POSTGRES_DB: postgres
volumes:
- postgres_data:/var/lib/postgresql/data
volumes:
postgres_data:
Tech Stack
PortNote is built using:
- Next.js + TypeScript
- TailwindCSS + DaisyUI
- PostgreSQL with Prisma ORM
- Lucide Icons
- Released under the MIT License
Who should use PortNote?
While advanced users may rely on tools like netstat, ss, or custom scripts, PortNote is ideal for anyone managing multiple services and containers who wants a centralized, visual way to track port assignments.
Get started
You can find the full project and installation instructions on GitHub:
🔗 https://github.com/crocofied/PortNote
Conclusion:
With version 1.1.0, PortNote introduces major quality-of-life improvements that make managing ports on self-hosted setups simpler than ever. Auto detection and smarter port suggestions help reduce friction, prevent conflicts, and improve clarity—especially for homelabbers and system administrators managing multiple services.
