| name | deepracer-dockerfile-update |
| description | Use when: updating Dockerfile.upstream or Dockerfile.upstream-adjusted to a new deepracer-on-aws-simapp version; syncing changes from a new upstream ECR image; inspecting docker image layers to find version bumps; reverse-engineering changes between simapp image versions. |
DeepRacer SimApp Dockerfile Update
Overview
Dockerfile.upstream tracks public.ecr.aws/aws-solutions/deepracer-on-aws-simapp verbatim.
Dockerfile.upstream-adjusted is a derived variant with local patches (e.g. removing ros-$ROS_DISTRO-desktop, adding custom web-video-server, different ROS repo config).
Apply changes found in the new upstream image to both files, but only apply changes to Dockerfile.upstream-adjusted where the relevant section exists and was not intentionally diverged.
Workflow
1. Confirm the image is available locally
docker images | grep deepracer-on-aws-simapp
If not present, pull it:
docker pull public.ecr.aws/aws-solutions/deepracer-on-aws-simapp:<VERSION>
2. Inspect image metadata
Get environment variables, entrypoint, working directory, and labels:
docker inspect public.ecr.aws/aws-solutions/deepracer-on-aws-simapp:<VERSION> | python3 -c "
import json, sys
data = json.load(sys.stdin)
cfg = data[0].get('Config', {})
print('Created:', data[0].get('Created'))
print('ID:', data[0].get('Id')[:20])
print('Env:', json.dumps(cfg.get('Env', []), indent=2))
print('Entrypoint:', cfg.get('Entrypoint'))
print('WorkingDir:', cfg.get('WorkingDir'))
"
3. Extract and compare layer history
Save full layer history for both the previous and new version:
docker history public.ecr.aws/aws-solutions/deepracer-on-aws-simapp:<OLD> \
--no-trunc --format "{{.CreatedBy}}" > /tmp/old_history.txt
docker history public.ecr.aws/aws-solutions/deepracer-on-aws-simapp:<NEW> \
--no-trunc --format "{{.CreatedBy}}" > /tmp/new_history.txt
diff <(sort /tmp/old_history.txt) <(sort /tmp/new_history.txt)
The diff output shows exactly which layers changed. Each line is a Dockerfile RUN, ENV, COPY, etc. instruction.
4. Identify changes
For each differing layer, determine the category:
| Category | Example | What to update |
|---|
| Package version bump | curl==8.16.0 → conda-forge::curl==8.19.0 | Version pin in both files |
| New package added | new apt/pip install | Add to both files |
| Package removed | layer deleted | Remove from both files |
| New ENV variable | ENV FOO=bar | Add ENV to both files |
| New COPY/layer | new COPY instruction | Evaluate if applicable to adjusted |
| Structural change | reordered layers | Update both files if order matters |
5. Update the Dockerfile headers
Always update the comment block at the top of Dockerfile.upstream:
# Optimized Dockerfile for public.ecr.aws/aws-solutions/deepracer-on-aws-simapp:<NEW_VERSION>
# Image ID: <first 12 chars of image ID>
# Base: Ubuntu 24.04 (Noble)
# Built: <Creation date from docker inspect>
# Optimized: <today's date>
For Dockerfile.upstream-adjusted, update the same header fields.
6. Apply changes
Use multi_replace_string_in_file to apply all edits in a single call across both files.
Key divergences in Dockerfile.upstream-adjusted — do NOT revert these intentional differences:
- Uses
ros-$ROS_DISTRO-web-video-server instead of ros-$ROS_DISTRO-desktop
- Does NOT include the Gazebo stable apt repo (
gazebo-stable.list)
- Adds
COPY ./bundle/src/deepracer_node_monitor/config/*.txt /opt/amazon/script/config/
- Build/log cleanup after ROS packages build:
rm -rf /opt/amazon/log /opt/amazon/build
7. Validate
After editing:
docker buildx build --check -f docker/Dockerfile.upstream .
docker buildx build --check -f docker/Dockerfile.upstream-adjusted .
Reference: Known Version History
Always add a row to this table when completing an update. Record the version, built date, and a concise summary of every change found in the layer diff.
| Image Version | Key Changes |
|---|
| v1.0.6 | Baseline for Dockerfile.upstream-adjusted |
| v1.0.8 | Baseline for Dockerfile.upstream |
| v1.0.9 | Added conda-forge::curl==8.16.0, libcurl==8.16.0 (security fix) |
| v1.0.11 | Bumped conda-forge::curl==8.19.0, conda-forge::libcurl==8.19.0 |
| v1.0.12 | Baseline (from v1.0.11 base) |
| v1.0.13 | Base Ubuntu layer refresh only; LABEL org.opencontainers.image.ref.name=ubuntu removed; no package changes |
| v1.1.3 | Base Ubuntu layer refresh; urllib3==2.7.0; conda-forge::curl==8.20.0, conda-forge::libcurl==8.20.0; added nginx==1.31.1 to conda install; removed 19-aws-sdk.list from rosdep init |
| v1.1.4 | Base layer rebuild only; no package changes |
| v1.1.7 | Base layer rebuild only; no package changes (layer history identical to v1.1.4) |
| v1.2.0 | Base layer rebuild only; no package changes (layer history identical to v1.1.7; base Ubuntu layer SHA unchanged) |
| v1.2.1 | cryptography==48.0.1 (was 46.0.7); nginx==1.31.2 (was 1.31.1) |
| v1.2.2 | Base layer rebuild only; no package changes (layer history identical to v1.2.1; built 2026-06-29) |
| v1.2.3 | conda-forge::curl==8.21.0, conda-forge::libcurl==8.21.0 (was 8.20.0); built 2026-07-13 |
| v1.2.4 | pillow==12.3.0 (was 12.2.0); nginx==1.31.3 (was 1.31.2); built 2026-07-17 |
