Skip to content

Container Standardization

Overview

All Docker containers follow a standardized naming convention for Watchtower compatibility and version control. This document covers container naming, tagging strategy, and image management.

Container Naming Convention

New Naming (Standardized)

benjr70/smart-smoker-backend:latest
benjr70/smart-smoker-backend:v1.2.3
benjr70/smart-smoker-backend:nightly

benjr70/smart-smoker-frontend:latest
benjr70/smart-smoker-frontend:v1.2.3
benjr70/smart-smoker-frontend:nightly

benjr70/smart-smoker-device-service:latest
benjr70/smart-smoker-device-service:v1.2.3
benjr70/smart-smoker-device-service:nightly

benjr70/smart-smoker-smoker:latest
benjr70/smart-smoker-smoker:v1.2.3
benjr70/smart-smoker-smoker:nightly

benjr70/smart-smoker-electron-shell:latest
benjr70/smart-smoker-electron-shell:v1.2.3
benjr70/smart-smoker-electron-shell:nightly

Benefits

  • ✅ Watchtower can update :latest tags automatically
  • ✅ Separate repository per service for clarity
  • ✅ Semantic versioning with v prefix
  • ✅ Consistent hyphen-separated naming
  • ✅ Clear environment strategy

Tagging Strategy

Floating Tags

  • nightly: Development builds (auto-deployed on master merge)
  • latest: Production releases (used by Watchtower on Raspberry Pi)

Immutable Tags

  • vX.Y.Z: Semantic version tags (never re-used, for rollback)
  • vX.Y: Minor version tags (optional)
  • vX: Major version tags (optional)

Promotion Flow

  1. Build once on master merge → push :nightly (dev cloud consumes this)
  2. When cutting a release, prod-deploy.yml builds the cloud images (backend + frontend) from the release tag and pushes :vX.Y.Z + :latest. Retagging :nightly is no longer used: :nightly can be a different commit than the one that was tagged.
  3. Re-deploying an already-released version skips the build entirely, so :vX.Y.Z stays immutable and :latest never moves backwards

Why This Matters: - Rollback: Switch to :vX.Y.Z instantly; floating tags move - Reproducibility: Exact artifacts for audits and bug reproduction - Operational Clarity: Dev uses :nightly, smoker uses :latest, cloud prod pins :vX.Y.Z

Watchtower Integration

Raspberry Pi Auto-Updates

Watchtower on Raspberry Pi devices automatically updates containers using :latest tags:

# /opt/smoker-device/smoker.docker-compose.yml on the Raspberry Pi
services:
  frontend:
    image: benjr70/smart-smoker-smoker:${VERSION:-latest}
    # Watchtower monitors this and updates automatically

:latest moves only when a GitHub Release is published, so the device updates once per release and never in between. It must never be pointed at :nightly — those bundles are built against dev-cloud.

Watchtower Configuration

The actual configuration on the device (see smoker.docker-compose.yml):

watchtower:
  image: containrrr/watchtower:armhf-latest # armv7; latest-dev is amd64 only
  volumes:
    - /var/run/docker.sock:/var/run/docker.sock
  # Scoped on purpose: unscoped, Watchtower would also manage portainer_agent
  # and itself, and an unattended self-update on armv7 is the one failure that
  # removes the device's ability to update anything else.
  command: --interval 300 --cleanup device_service frontend_smoker electron_shell

Watchtower recreates containers from the running container's config, not from the compose file — so compose changes require a Device Deploy dispatch. See Physical Smoker Device.

Environment Tag Usage

Development

Tag: nightly
Deployment: Auto-deploy on master merge
Location: dev-cloud

services:
  backend:
    image: benjr70/smart-smoker-backend:nightly

Production (Cloud)

Tag: vX.Y.Z (pinned versions)
Deployment: On GitHub Release publish (merge of the release PR), then the production environment approval gate — required reviewer + 5-minute wait timer, pending removal (Release Process)
Location: prod-cloud

services:
  backend:
    image: benjr70/smart-smoker-backend:v1.2.3

Production (Raspberry Pi)

Tag: latest (Watchtower auto-updates)
Deployment: Automatic via Watchtower
Location: Raspberry Pi devices

services:
  backend:
    image: benjr70/smart-smoker-backend:latest

Image Management

Building Images

# Build all images
docker compose -f docker-compose.build.yml build

# Build specific service
docker compose -f docker-compose.build.yml build backend

Tagging Images

# Tag for nightly
docker tag benjr70/smart-smoker-backend:build benjr70/smart-smoker-backend:nightly

# Tag for release
docker tag benjr70/smart-smoker-backend:build benjr70/smart-smoker-backend:v1.2.3
docker tag benjr70/smart-smoker-backend:build benjr70/smart-smoker-backend:latest

Publishing Images

# Push nightly
docker push benjr70/smart-smoker-backend:nightly

# Push release tags
docker push benjr70/smart-smoker-backend:v1.2.3
docker push benjr70/smart-smoker-backend:latest

Version Management

Semantic Versioning

Follow Semantic Versioning: - MAJOR: Incompatible API changes - MINOR: Backward-compatible functionality - PATCH: Backward-compatible bug fixes

Version Tags

# Create version tag
git tag -a v1.2.3 -m "Release version 1.2.3"
git push origin v1.2.3

# GitHub Actions automatically:
# 1. Builds images
# 2. Tags with v1.2.3 and latest
# 3. Pushes to registry

Rollback Strategy

Using Version Tags

# Rollback to specific version
docker compose -f cloud.docker-compose.yml pull benjr70/smart-smoker-backend:v1.2.2
docker compose -f cloud.docker-compose.yml up -d backend

Using Deployment Backup

See Rollback for automated rollback procedures.

Best Practices

Image Naming

  1. Use Hyphens: smart-smoker-backend not smart_smoker_backend
  2. Be Descriptive: Clear service names
  3. Consistent: Same pattern across all services

Tag Management

  1. Never Re-tag: Immutable tags (vX.Y.Z) should never change
  2. Build Once Per Tag: Cloud release images are built from the release tag once; re-deploys reuse the published digest instead of rebuilding
  3. Document Versions: Keep changelog of versions

Watchtower

  1. Use :latest: Only for Watchtower auto-updates
  2. Pin in Production: Use version tags for production cloud
  3. Test Updates: Verify Watchtower updates work correctly

Last Updated: 2025-12-07