PortNote is a web application designed to help developers and DevOps teams track which ports are in use across their servers and virtual machines. Built by the creator of CoreControl, it replaces manual spreadsheets with a structured interface for documenting port assignments. This eliminates port conflicts during deployment and improves infrastructure visibility. PortNote is ideal for teams managing multiple services on shared networks, where port collisions cause downtime or debugging headaches.
The system includes a web dashboard for adding servers, assigning ports to services, and viewing usage across systems. It also features a random port generator to help users find available ports quickly. With an integrated agent and PostgreSQL backend, PortNote provides a persistent, searchable record of port allocations that can be accessed from anywhere.
What You Get
- Centralized Port Tracking - Document which ports are assigned to specific services on any server or VM through a web interface, eliminating spreadsheet chaos.
- Server and VM Management - Add and organize multiple servers/VMs with custom names and descriptions to correlate port usage by host.
- Random Port Generator - Generate a random, unused port number to avoid conflicts when deploying new services.
- Authentication and Secure Access - Login with username/password credentials to protect port documentation from unauthorized changes.
- Docker-Ready Deployment - Deploy the full stack with a single docker-compose.yml file including web UI, agent, and PostgreSQL database.
Common Use Cases
- Building a multi-service microarchitecture - When deploying 10+ containers on a single host, PortNote helps avoid port collisions between services like Redis, PostgreSQL, and custom APIs.
- Managing shared development environments - Teams working in a shared lab or staging environment use PortNote to coordinate which ports are allocated for testing databases, proxies, and backend services.
- Problem: Port conflicts during deployment → Solution: Use PortNote to check assigned ports before starting a new service - Before running
docker run -p 3001:3000, check PortNote’s dashboard to confirm port 3001 isn’t already assigned to another team member’s service.
- DevOps teams managing hybrid cloud infrastructure - Administrators tracking ports across on-prem VMs and cloud instances use PortNote to maintain a single source of truth for port allocations.
Under The Hood
PortNote is a full-stack web application designed to manage server and port configurations through an intuitive interface. It combines a React-based frontend with a Next.js backend, enabling users to scan, track, and manage network ports efficiently. The system integrates database operations via Prisma and includes authentication and search capabilities to enhance usability.
Architecture
This project adopts a monolithic architecture with distinct frontend and backend layers, leveraging Next.js for rendering and API handling.
- The system follows REST principles with organized API routes grouped by functionality
- Database interactions are handled through Prisma, ensuring type safety and structured data access
- Clear separation between UI components and backend logic promotes maintainability
Tech Stack
The project is built using TypeScript and Next.js, emphasizing modern web development practices.
- The core is powered by TypeScript and Next.js for full-stack functionality and server-side rendering
- Prisma is used as the ORM to manage database interactions with strong typing
- Frontend components are built with React and styled using Tailwind CSS for responsive design
- Authentication and data handling are supported through js-cookie, jsonwebtoken, and axios libraries
Code Quality
Code quality varies across the codebase, showing functional structure but lacking comprehensive testing.
- Error handling is applied consistently across API routes, though some validation and logging are missing
- The codebase demonstrates reasonable organization with separation of concerns in component structure
- Type safety is enforced through TypeScript, contributing to code clarity and reliability
What Makes It Unique
PortNote stands out with its blend of web management and local scanning capabilities.
- The integration of Fuse.js enables intelligent search functionality for port data
- Cookie-based state persistence enhances user session management in a web context
- A Go agent is used for system-level port scanning, offering a unique hybrid approach to network monitoring
- Prisma ORM is thoughtfully integrated with Next.js API routes, enabling efficient CRUD operations