Dockerized TDM.
This repository contains files necessary to build and run a TDM Docker container which runs in conjunction with the THREDDS Docker container to provide indexes for GRIB featureCollections. The container can run on a different VM from THREDDS provided it has access to the same data directory THREDDS has access to via an NFS mount, for example. The Unidata TDM Docker images associated with this repository are available on DockerHub.
See tags listed on DockerHub.
Before you begin using this Docker container project, make sure your system has Docker installed. Docker Compose is optional but recommended.
You can either pull the image from DockerHub with:
docker pull unidata/tdm-docker:<version>Or you can build it yourself with:
- Clone the repository:
git clone https://github.com/Unidata/tdm-docker.git - Navigate to the project directory:
cd tdm-docker - Build the Docker image:
docker build -t tdm-docker:<version> .
To run the TDM Docker container, beyond a basic Docker setup, we recommend installing docker-compose. docker-compose serves two purposes:
-
Reduce headaches involving unwieldy
dockercommand lines where you are runningdockerwith multiple volume mounts and port forwards. In situations like these,dockercommands become difficult to issue and read. Instead, the lengthydockercommand is captured in adocker-compose.ymlthat is easy to read, maintain, and can be committed to version control. -
Coordinate the running of two or more containers. This can be useful for taking into account the same volume mountings, for example.
However, docker-compose use is not mandatory. There is an example docker-compose.yml in this repository.
Once you have completed your setup you can run the container with:
docker-compose up -d tdmThe output of such command should be something like:
Creating tdm
To stop this container:
docker-compose stop tdmTo clean the slate and remove the container (not the image, the container):
docker-compose rm -f tdmUpgrading to a newer version of the container is easy. Simply stop the container via docker or docker-compose, followed by
docker pull unidata/tdm-docker:<version>and restart the container. Refer to the new version from the command line or in the docker-compose.yml.
docker pswhich should give you output that looks something like this:
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
d4a1424d9375 unidata/tdm-docker:5.10 "/entrypoint.sh tdm.…" 5 weeks ago Up 5 weeks tdm
To run the TDM Docker container, beyond a basic Docker setup, we recommend installing docker-compose. We will assume you have knowledge on how to configure a TDS.
version: '3'
services:
tdm:
image: unidata/tdm-docker:5.10
container_name: tdm
volumes:
- /path/to/your/thredds/directory:/usr/local/tomcat/content/thredds
- /path/to/your/data/directory1:/path/to/your/data/directory1:ro
env_file:
- "compose${THREDDS_COMPOSE_ENV_LOCAL}.env"In the docker-compose.yml file, volumes mapping section, you will point the TDM to the TDS content root directory and the /data directory corresponding to the DataRoots element in threddsConfig.xml. E.g.,
volumes:
# data directory
- /data/:/data/
# TDS content root directory
- ~/tdsconfig/:/usr/local/tomcat/content/thredds/
- /logs/tdm/:/usr/local/tomcat/content/tdm/logsAlso note the /data directory will be the same directory the TDS container will be pointing to.
The container is configured with these environment variables:
| Setting | Environment variable | Example/default |
|---|---|---|
| TDS content root | TDS_CONTENT_ROOT_PATH |
/usr/local/tomcat/content |
| TDS trigger password | TDM_PW |
No default; required |
| TDS base URL | TDS_HOST |
https://tds.example.test/ |
| Maximum Java heap | TDM_XMX_SIZE |
6G |
| Minimum Java heap | TDM_XMS_SIZE |
1G |
| Runtime user ID | TDM_USER_ID |
1000 |
| Runtime group ID | TDM_GROUP_ID |
1000 |
Do not put a real password in the tracked compose.env template. Copy it to the ignored compose.local.env, set TDM_PW there, and select it when starting Compose:
cp compose.env compose.local.env
chmod 600 compose.local.env
THREDDS_COMPOSE_ENV_LOCAL=.local docker compose up -d tdmThe env_file entry in docker-compose.yml expands this variable as compose${THREDDS_COMPOSE_ENV_LOCAL}.env; setting it to .local therefore selects compose.local.env. Leaving it unset selects the tracked compose.env template.
The TDM receives this password through its environment and passes it to the Java process as a command-line argument. Limit access to the Docker host and its process/container metadata accordingly.
The TDM process runs under the numeric UID/GID specified by TDM_USER_ID and TDM_GROUP_ID, which default to 1000/1000. At startup, the container creates tdm user or group entries only when those numeric IDs do not already exist. If the IDs already belong to named identities in the image, those identities are used without modification.
Only the TDM log and Java Preferences directories are made writable by the runtime UID/GID. The JAR, scripts, and logging configuration remain root-owned.
The TDM notifies the TDS through its protected collection-trigger endpoint. Create a Tomcat user named tdm with only the tdsTrigger role. The username is currently fixed by tdm.sh.
For example, add the following role and user to the tomcat-users.xml mounted by the TDS container:
<tomcat-users>
<role rolename="tdsTrigger"/>
<user username="tdm"
password="DIGESTED_PASSWORD"
roles="tdsTrigger"/>
</tomcat-users>Generate DIGESTED_PASSWORD using the SHA-512 procedure in the Tomcat Docker documentation. Set TDM_PW to the original cleartext password used to produce that digest, not to the digest itself. Mount tomcat-users.xml read-only in the TDS container and restart the TDS after changing it.
Set the TDS_HOST to the TDS base HTTPS URL reachable from the TDM container.
If authentication fails, search the TDM logs for trigger. A failure resembles:
fc.example.log:2026-01-01T00:00:00.000 +0000 WARN - FAIL send trigger to https://tds.example.test/thredds/admin/collection/trigger?trigger=never&collection=example status = 401Use the reported status to narrow down the cause:
| Symptom | Likely area |
|---|---|
HTTP 401 |
The tdm password does not match the password used to generate the TDS digest. |
HTTP 403 |
The tdm user is authenticated but is missing the tdsTrigger role. |
| Connection or TLS failure | Check TDS_HOST, DNS and network routing, and certificate trust. |
In order to cite this project, please simply make use of the Unidata THREDDS Data Server DOI: https://doi.org/10.5065/D6N014KG https://doi.org/10.5065/D6N014KG
If you have a question or would like support for this TDM Docker container, consider submitting a GitHub issue. Alternatively, you may wish to start a discussion on the THREDDS Community mailing list: thredds@unidata.ucar.edu.
For general TDS questions, please see the THREDDS support page.