PortNote is a web-based port management tool designed for system administrators and DevOps engineers who need to track which services are using which ports across multiple servers and VMs. It eliminates the chaos of spreadsheets and manual tracking by offering a structured, searchable interface to assign, document, and audit port usage. Built by the creator of CoreControl, it brings operational clarity to a commonly overlooked aspect of infrastructure management.
The application is built with Next.js and TypeScript on the frontend, powered by PostgreSQL via Prisma ORM for data persistence, and styled with Tailwind CSS and daisyUI. It includes a companion agent for automated data collection and deploys via Docker Compose with a secure, containerized stack including PostgreSQL and authentication layers.
What You Get
- Centralized Port Dashboard - View all assigned ports across servers and VMs in a single, searchable interface with visual indicators for conflicts and usage.
- Server and VM Management - Add and organize servers and VMs with custom names and metadata to associate port assignments with specific systems.
- Port Assignment Documentation - Add notes, service names, and descriptions to each port entry to clarify purpose and ownership for team collaboration.
- Random Port Generator - Generate unused port numbers within a configurable range to avoid conflicts when deploying new services.
- JWT-Based Authentication - Secure access with username/password login and JWT token validation to protect port configuration data.
- Docker-Ready Deployment - Deploy with a single docker-compose.yml file including PostgreSQL database, web server, and agent for automated data sync.
Common Use Cases
- Managing multi-server deployments - A DevOps engineer uses PortNote to track which ports are used by microservices across 20+ VMs to prevent collisions during deployments.
- Onboarding new team members - A sysadmin documents port usage for legacy systems so new hires can quickly understand service mappings without digging through old docs.
- Avoiding port conflicts in CI/CD - A developer uses the random port generator to pick safe ports for test containers during automated pipeline runs.
- Auditing infrastructure for compliance - A security analyst exports port assignments to verify no unauthorized services are running on restricted ports.
Under The Hood
Architecture
- Next.js App Router with API routes directly invoking PrismaClient without service or repository layers, leading to scattered data access logic and poor separation of concerns
- Client-side components mix UI rendering, state management, and API calls without centralized state patterns or abstraction
- Authentication is hardcoded with JWT and environment variables, lacking middleware, guards, or extensible auth pipelines
- Directory structure follows Next.js conventions but lacks domain-based modularization, resulting in a flat, hard-to-navigate codebase
- No dependency injection, interfaces, or testable abstractions—PrismaClient is tightly coupled to endpoints and components
Tech Stack
- Modern Next.js 15 with React 19 and TypeScript enabling server-side rendering and strong type safety
- Prisma ORM with PostgreSQL via Docker for type-safe database operations and migration workflows
- Docker Compose with multi-stage builds using Node.js 20 Alpine for optimized containerized deployment of web and agent services
- Tailwind CSS and DaisyUI for utility-first, themable UI with night mode as default for low-light sysadmin workflows
- JWT-based stateless authentication with client-side token persistence and server-side validation
- Comprehensive TypeScript configuration with path aliases and module resolution for improved code structure and IDE support
Code Quality
- Absence of test files and assertions leaves critical logic unverified and vulnerable to regressions
- Inconsistent error handling exposes internal details to clients and lacks user-friendly fallbacks
- API endpoints use ambiguous field names and untyped request interfaces, reducing clarity and maintainability
- Magic numbers dominate business logic without enums or constants, making intent opaque and error-prone
- UI components rely on imperative state management with direct DOM manipulation, lacking reusable abstractions
- No linting or formatting rules enforced, resulting in inconsistent style and potential bugs
What Makes It Unique
- Dual-entity modeling where servers and ports are interlinked with intelligent cascading deletion to preserve VM hierarchy integrity
- Lightweight JWT validation combining signature checks with static user_secret comparison, eliminating session overhead
- Port scanning implemented as audit event logging rather than live scanning, creating a persistent, queryable network topology history
- Type-coded API endpoints enforce a unified CRUD model across server, VM, and port entities while preserving domain semantics
- Night-mode-first UI design with Tailwind and DaisyUI tailored for sysadmins operating in low-light infrastructure environments
- Automatic dashboard redirection post-authentication to streamline user workflow without compromising server-side security