Skip to main content
Version: v26.0-RC

Updating Port Mappings for Containers

Summary​

Container runtimes do not allow port mappings to be added or modified after a container is launched. To update port mappings, a new container must be created using the previous container’s stateful data. This can be accomplished using volume mounts or, in Docker-only scenarios, 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. Container port mappings must be defined at container startup. If the container does not have the correct mapping, the origin will be inoperative on that gateway.

Port mappings can be updated in one of the following ways:

  • By stopping the container and recreating it using volume mounts (recommended)
  • By stopping the container, committing it to a new image, and creating a new container (Docker only)

DH2i recommends using volume mounts to persist data between container deployments. For more information, see Understanding Volume Mounts.

Updating Port Mappings for Containers with Volume Mounts​

  1. Gather information about the container.

    1. On the host machine running the container, inspect the container configuration:

      docker inspect <CONTAINER_NAME>

    2. Under Config, record the value of Image (the registry and repository used to create the container).

    3. Under Config → Env, record the value of DX_HOSTNAME.
      If this variable does not exist, record the value of Hostname under Config instead.
      DX_HOSTNAME takes precedence over Hostname.

    4. Under Mounts, record the volume mounts (including /etc/dh2i). These volumes will be reused by the new container.

    5. Under Network Settings, record the existing port mappings. These must be included in the new container run command.

  2. Stop the container.

    docker stop <CONTAINER_NAME>

  3. Remove the container.

    docker rm <CONTAINER_NAME>
    danger

    Removing a container that stores data outside of volume mounts will permanently destroy that data.

    If applications in the container require persistent storage and do not use volumes, the container must be recreated in a way that preserves its filesystem state. This workflow is supported using docker commit in Docker-based deployments.

    This approach is not recommended for long-term use. DH2i strongly recommends using volume mounts for all persistent DxEnterprise and DxOdyssey data.

  4. Recreate the container with the existing port mappings, the new port mapping, the original hostname, the volume mount, and the original image.

If DX_HOSTNAME was previously set:

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>

If DX_HOSTNAME was not set:

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.

  1. The container will automatically rejoin the cluster or gateway group. After joining, you can configure tunnels to use the updated port mappings.

Updating Port Mappings for Containers without Volume Mounts (Docker Only)​

In environments where volume mounts were not used, the container can be committed to a new image and relaunched. This method is not recommended for long-term persistence.

  1. Gather container information using:

    docker inspect <CONTAINER_NAME>

  2. Update the container:

    1. Stop the container:
    docker stop <CONTAINER_NAME>
    1. Commit the container to a new image:
    docker commit <CONTAINER_NAME> <NEW_IMAGE_NAME>
    1. Remove the old container:
    docker rm <CONTAINER_NAME>
    1. Create a new container using the committed image:
    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>
    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.

  3. 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​