Skip to content

feat: add cryptographically signed Docker images with Cosign#136

Open
FrameAutomata wants to merge 2 commits into
tracewayapp:mainfrom
FrameAutomata:feat/signed_docker_images
Open

feat: add cryptographically signed Docker images with Cosign#136
FrameAutomata wants to merge 2 commits into
tracewayapp:mainfrom
FrameAutomata:feat/signed_docker_images

Conversation

@FrameAutomata
Copy link
Copy Markdown
Collaborator

Summary

Implements cryptographically signed Docker images for Traceway using Cosign and GitHub OIDC, addressing issue #133.

What Changed

  • ✅ Updated release workflow to build and push Docker images to GHCR on every release
  • ✅ Added Cosign signing with keyless GitHub OIDC authentication (no secrets management)
  • ✅ Published two image variants:
    • Full image (includes ClickHouse, PostgreSQL, supervisord) - ~313MB
    • Minimal image (lightweight, for external databases) - ~21.3MB
  • ✅ Tagged images with both version and latest/minimal tags
  • ✅ Added comprehensive user documentation (DOCKER_SIGNATURES.md)
  • ✅ Updated README to reference Docker signature verification guide

Why This Approach

  • Keyless signing: No manual key management or GitHub secrets needed
  • Industry standard: Cosign is CNCF-endorsed for supply chain security
  • Two images: Users can choose based on their deployment model
  • Transparent: Uses GitHub's OIDC tokens (publicly verifiable)
  • Efficient: Docker BuildX cache speeds up minimal image builds

Testing Performed

  • ✅ Both Dockerfiles build successfully locally
  • ✅ Full image: 313MB compressed, 1.36GB uncompressed, 17 layers
  • ✅ Minimal image: 21.3MB compressed, 86.1MB uncompressed, 4 layers
  • ✅ Both images have correct architecture (amd64)
  • ✅ Binary is present and executable in both images
  • ✅ supervisord (v4.2.5) verified in full image
  • ✅ GitHub Actions workflow syntax validated

How It Works

  1. Maintainer triggers "Release Traceway" workflow
  2. Release job builds and tags frontend/backend, creates GitHub release
  3. Build-Docker job (runs after release):
    • Builds and pushes full image to GHCR
    • Builds and pushes minimal image to GHCR
    • Signs both images with Cosign using GitHub OIDC (keyless)
  4. Images available with signatures for users to verify

User Documentation

See DOCKER_SIGNATURES.md for:

  • How to install Cosign (macOS, Linux, Windows)
  • How to verify image signatures
  • Docker Compose examples for both image types
  • Troubleshooting common issues

Closes #133

- Build and push Docker images to GHCR on every release
- Sign images with Cosign using keyless GitHub OIDC authentication
- Publish both full (all-in-one) and minimal (lightweight) image variants
- Tag images with both version and latest/minimal tags
- Add comprehensive user documentation for signature verification
- Update README to reference Docker signature verification guide

Closes tracewayapp#133
@FrameAutomata FrameAutomata self-assigned this May 13, 2026
@sebakubisz
Copy link
Copy Markdown

Could a :sqlite variant be added to this PR alongside :latest and :minimal? Dockerfile.sqlite already exists in the repo and produces a single-binary image with no external dependencies, which is the mode that fits a small VPS.

@dusanstanojeviccs
Copy link
Copy Markdown
Collaborator

@FrameAutomata I would add all docker containers for https://docs.tracewayapp.com/server to the docker, to help people self host based on their specific need

@FrameAutomata
Copy link
Copy Markdown
Collaborator Author

@dusanstanojeviccs @sebakubisz On it

- Add SQLite image (Dockerfile.sqlite) for embedded deployments
- Build and sign SQLite image alongside full and minimal variants
- Update documentation with all three image variants and use cases
- Add Docker Compose example for SQLite embedded mode
- Improve image descriptions and deployment guidance

Addresses feedback on tracewayapp#136
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Signed docker images

3 participants