Define a convention on TCP/UDP ports used by development stacks

Background

In many of our projects, we deploy local development servers (e.g., an API and a Database) on our development machines for testing purposes. These servers expose a TCP (occasionally UDP) port on our local machine. Currently, there is no standardized convention for the usage of these TCP/UDP ports across projects. For instance, some projects use port 8000 for web APIs, while others use 8080.

Note: This intentionally simplifies the distinction between TCP and UDP ports and assumes we don't want two distinct services, one on TCP and one on UDP, running on the same port number. Although technically possible, it's deemed cumbersome for our purposes.

Problem Statement

The absence of a convention on TCP/UDP port assignments for local development services leads to two issues:

• After starting a local development stack, it's unclear where the services are listening, causing delays when switching between projects.
  • This becomes more pronounced with the shift to docker-compose-based local dev stacks, initiated with a simple docker compose up -d.
• Running two local development stacks simultaneously is usually impossible due to port conflicts.
  • This often occurs when transitioning from developing project A to reviewing project B.

Proposition

We can address the problem by establishing a convention for TCP/UDP port assignments.

The proposed convention is to use port XXXY for every server in our systems, where:

• Y is a number indicating the type of service:
  • UI is always on Y=0
  • Backend server (+/- API) is on Y=1
  • Database is on Y=2
  • Y=3 to 5 are reserved for potential generic usage
  • Y=6 to 9 are available for non-generic services (e.g., a second backend server)
• XXX is a number reserved per project (Github repository)
  • Each Github repository will reserve a number in a centralized reference.
  • Repositories may reserve multiple numbers if needed, and these numbers are contiguous. If the need wasn't anticipated, the project is moved to other contiguous numbers.
  • To determine where XXX starts, we need a broad port range to accommodate all our projects. Since we don't have many other services running on our development machines and the TCP/UDP port ranges are cluttered with various services, we can use any meaningful port range for these assignments, reserving some numbers for external services if conflicts arise.
  • XXX will hence start at 800, with the 800 and 808 ranges already reserved due to known conflicts with many of our (not yet migrated) projects and other web servers.

Feedback and implementation

All feedbacks are welcomed, after that I will transition this to a Wiki entry.