“Wait, What’s on Port 3333?”

In a homelab with over 125 Docker containers, it’s easy to lose track of port assignments. I built a tool that scans my docker-compose files and instantly tells me what service is running on any port.

The Problem:

Running a self-hosted homelab with tons of Docker containers is an exercise in precision—and sometimes, detective work. While I follow strict best practices for container organization and documentation, occasionally a new service slips through before I’ve jotted down its port assignments. Despite using PortNote — a fantastic self-hosted tool for documenting ports across my network —”mystery ports” showing up during port scans are still an occasional reality. When they do show up, I’m left staring at an unlabeled port wondering: “Wait… what’s running on 3333 again?”

The Solution:

I wrote a small but effective script that solves this cleanly. It scans all docker-compose.yml files under my /volume1/docker/ directory for a specified port and returns the directory name where that file lives. Because I use a strict naming convention (every service lives in a directory named after the app), the answer is always accurate and human-readable with zero guesswork.

Why it works:

  • Best-practice Docker structure
    Every self-hosted app I run lives in its own directory (e.g. /volume1/docker/immich/, /volume1/docker/beszel/), containing the docker-compose.yml and all persistent data. This means one folder = one service.
  • Quick, reliable lookups
    A single command gives me the service name behind any port. No more mystery ports. No more grepping through 125+ config files by hand.
  • Easily extensible
    The script is minimal and fast, but could easily be expanded to output additional metadata or be used as part of a CI (continuous integration) check.

Under the hood

All code and usage instructions are available on GitHub!

Shoutout!

Huge thanks to PortNote for making port documentation effortless—and for inspiring this complementary tool.