Updating Port Mappings for DxOdyssey Docker Containers

Applies to…

  • DxOdyssey 19.0 and newer


Linux Docker containers require that ports are mapped when the container is started. If another port needs to be mapped for a DxOdyssey gateway, a new container must be connected to the gateway group with additional port mappings using -p arguments in the “docker run” command.


A tunnel origin, whether a single gateway or multiple gateways (.ACTIVE, .PART, etc.), must have a listener on the gateway 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. A port cannot be mapped to an existing container, but a new container can be created that utilizes the previous configurations to rejoin the gateway group quickly. This article assumes that the Docker container is using a mounted volume to store the contents of its /etc/dh2i folder.

    1. 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 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, but only one value is required.
      4. Under “Mounts”, save the name of the /etc/dh2i volume mount. This is the storage for DxOdyssey’s 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.
    2. Stop the container by executing “docker stop < CONTAINER_NAME >”
    3. Remove the container by executing “docker rm < CONTAINER_NAME >”
    4. 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 used by DxOdyssey. 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 >
      NOTE: For additional information on creating DxOdyssey Docker containers, see this KB article.
    5. The DxOdyssey container will automatically rejoin the gateway group. After joining, the user can configure tunnels that will utilize the updated port mappings.

Additional information