Port mapping

[tjpeel]

Apologies if this is obvious but regarding port mapping, the best practice says:

Avoid assigning static port bindings to containers. Instead, use random assigned host ports _builder.WithPortBinding(ushort, true) and retrieve the mapped port with _container.GetMappedPublicPort(ushort)

So if I'm building a container and assign port 3000 to map from the host, if the container being built runs a service on port 3000 too, how do you instruct the service to change to the randomly assigned one? I have see an approach being used in the Kafka container builder - is that the only one?

Some additional snippets within the docs for things like this would be really useful to explain the best practice guidance.

Many thanks

[HofmeisterAn]

how do you instruct the service to change to the randomly assigned one?

I am not completely sure if I understood your question correctly. However, the service running inside the container will always use the default port. But publicly it will be (available) mapped to a random port to avoid conflicts.

E.g. _builder.WithPortBinding(3000, true) exposes the port 3000 to other containers in the same network. From the test host you access the service through the mapped port _container.GetMappedPublicPort(3000).

I have see an approach being used in the Kafka container builder

If you really need the random assigned host port to configure your service running inside the container, Kafka's approach is the right way. Please note, this is an edge case and is usually not necessary.

[tjpeel]

Ahh, so it's container port first and then host port as the second param. I have baked in muscle memory of docker compose port mappings that are host then container ie. 3000:3000.

Ok, so I can see how the randomly chosen port now makes sense in terms of how to connect from host to container.

Thanks for clarifying.

[HofmeisterAn]

so it's container port first and then host port as the second param.

To avoid any misunderstanding. It is WithPortBinding(hostPort, containerPort), but for the random assigned host ports it is WithPortBinding(containerPort, true):

testcontainers-dotnet/src/Testcontainers/Builders/IContainerBuilder`2.cs

Lines 164 to 171 in eedd883

	/// <summary>
	/// Binds the container port to a random host port.
	/// </summary>
	/// <param name="port">The container port.</param>
	/// <param name="assignRandomHostPort">Determines whether Testcontainers assigns a random host port or not.</param>
	/// <returns>A configured instance of <typeparamref name="TBuilderEntity" />.</returns>
	[PublicAPI]
	TBuilderEntity WithPortBinding(int port, bool assignRandomHostPort = false);