Skip to main content

Version: v23.0

Updating Port Mappings for Containers

Summary

Docker does not allow container port mappings to be added or modified after launch, so the port mappings must be applied to a new container that uses the previous container's stateful data. This can be accomplished using volume mounts or docker commit.

For Kubernetes port mappings, see the Understanding Tunnel Origins KB article.

Information

A tunnel origin, whether a single Vhost/gateway or multiple Vhosts/gateways (.ACTIVE, .PART, etc.), must have a listener to function. In Docker, the listening port must be mapped when the container is launched. If the container does not have the correct mapping, the origin will be inoperative on that gateway. The port can be mapped in two ways:

By stopping the container and removing the image, then reusing the volume mount to start a new container with updated port mappings.
By stopping the container and committing the image, the starting the new container with updated port mappings.

DH2i recommends using volume mounts for containers to persist data between deployments. For more information about volume mounts, view the Understanding Volume Mounts KB article.

Updating Port Mappings for Containers with Volume Mounts

Gather information about the container.
1. On the host machine running the container, execute docker inspect <CONTAINER_NAME>. This command will list information about the container's configuration, including mounted volumes and mapped ports.
2. Under Config, save the value of Image. This is the registry and repository that was used to create the container.
3. Under Config > Env, save the value of the DX_HOSTNAME variable. If this environment variable doesn't exist, save the value of Hostname under Config instead. DX_HOSTNAME takes precedence over Hostname.
4. Under Mounts, save the name of any volume mounts, including the /etc/dh2i volume mount. This is the storage for DH2i's software configuration files, and will be reused by the new container.
5. Under Network Settings, save the listed port mappings. These mappings must be included in the new docker run command so that pre-existing configurations will function correctly.
Stop the container by executing docker stop <CONTAINER_NAME>.
Remove the container by executing docker rm <CONTAINER_NAME>.

danger
Removing a container that has data stored in locations other than the volume mount will destroy that data. If other applications in the container do not have volume mounts and have data that needs to be persisted, use docker commit instead.
Execute docker run with the previously configured port mappings for the container, the new port mapping, the previous DX_HOSTNAME or hostname, the volume mount, and the tag for the previous image. The -p flag is for each mapped port, -d runs the container detached so the host machine's command line is usable after the container is run, -v mounts the pre-existing volume to the new container, and -e specifies the DX_HOSTNAME environment variable. If no DX_HOSTNAME variable existed for the previous container, use -h <HOSTNAME> instead. For example:
```
docker run -p 7979:7979 -p <NEW_PORT_MAPPING> -d -v <VOLUME_NAME>:/etc/dh2i -e "DX_HOSTNAME=<CONTAINER_HOSTNAME>" --name <CONTAINER_NAME> <IMAGE_NAME>
```
```
docker run -p 7979:7979 -p <NEW_PORT_MAPPING> -d -v <VOLUME_NAME>:/etc/dh2i -h <CONTAINER_HOSTNAME> --name <CONTAINER_NAME> <IMAGE_NAME>
```
info
For additional information on creating containers, see Creating a Container with Tunnel Origins.
The container will automatically rejoin the cluster or gateway group. After joining, you can configure tunnels that will utilize the updated port mappings.

Updating Port Mappings for Containers without Volume Mounts

Containers may also be "committed" and used as the base image for a new container in situations when there are no volumes associated with the old container. This is not the recommended way to persist container data, so volume mounts should be used to avoid potential data loss in the future. Do the following:

Gather information about the container.
1. On the host machine running the container, execute docker inspect <CONTAINER_NAME>. This command will list information about the container's configuration, including mounted volumes and mapped ports.
2. Under Config > Env, save the value of the DX_HOSTNAME variable. If this environment variable doesn't exist, save the value of Hostname under Config instead. DX_HOSTNAME takes precedence over Hostname.
3. Under Network Settings, save the listed port mappings. These mappings must be included in the new docker run command so that pre-existing configurations will function correctly.
Create a new container with the updated port mappings.
1. Execute docker stop <CONTAINER_NAME> to stop the container.
2. Execute docker commit <CONTAINER_NAME> <NEW_IMAGE_NAME> using the current container and a new image name to create a new image based on the container.
3. Execute docker container rm <CONTAINER_NAME> to remove the old container.
4. Execute docker run with the previously configured port mappings for the container, the new port mapping, a new /etc/dh2i volume, the same host name, and the newly committed image. The -p flag is for each mapped port, -d runs the container detached so the host machine's command line is usable after the container is run, and -h specifies the host name used by the container. For example:
```
docker run -p 7979:7979 -p <NEW_PORT_MAPPING> -d -v dxovol:/etc/dh2i -e "DX_HOSTNAME=<CONTAINER_HOSTNAME>" --name <CONTAINER_NAME> <NEW_IMAGE_NAME>
```
```
docker run -p 57979:7979 -p <NEW_PORT_MAPPING> -d -v dxovol:/etc/dh2i -h <HOST_NAME> --name <CONTAINER_NAME> <NEW_IMAGE_NAME>
```
  tip
  DH2i recommends using volume mounts to store DxOdyssey and DxEnterprise configuration information. See the Understanding Volume Mounts KB article for information about volume mounts.
The container will automatically rejoin the cluster or gateway group. After joining, you can configure tunnels that will utilize the updated port mappings.

Additional information