From 6c19674db714f5d43fcc699982aa277334cabf41 Mon Sep 17 00:00:00 2001 From: AARUSHGAUR Date: Wed, 23 Sep 2026 18:48:33 +0530 Subject: [PATCH 1/5] Add workflow to publish the Docker image on releases --- .github/workflows/docker-publish.yaml | 93 +++++++++++++++++++++++++++ README.md | 14 ++++ 2 files changed, 107 insertions(+) create mode 100644 .github/workflows/docker-publish.yaml diff --git a/.github/workflows/docker-publish.yaml b/.github/workflows/docker-publish.yaml new file mode 100644 index 00000000..bb6b302c --- /dev/null +++ b/.github/workflows/docker-publish.yaml @@ -0,0 +1,93 @@ +name: Docker Publish + +on: + release: + types: + - published + workflow_dispatch: + inputs: + tag: + description: 'Tag for the published image (defaults to sha-)' + required: false + type: string + +permissions: + contents: read + +jobs: + docker-publish: + runs-on: ubuntu-latest + permissions: + contents: read + packages: write + env: + REGISTRY: ghcr.io + IMAGE_NAME: ${{ github.repository }} + DOCKER_HUB_USERNAME: ${{ secrets.DOCKER_HUB_USERNAME }} + DOCKER_HUB_PASSWORD: ${{ secrets.DOCKER_HUB_PASSWORD }} + steps: + - name: Checkout code + uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 + + - name: Set up Docker Buildx + uses: docker/setup-buildx-action@e468171a9de216ec08956ac3ada2f0791b6bd435 # v3.11.1 + + - name: Log in to the GitHub Container Registry + uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0 + with: + registry: ${{ env.REGISTRY }} + username: ${{ github.actor }} + password: ${{ secrets.GITHUB_TOKEN }} + + - name: Extract metadata + id: meta + uses: docker/metadata-action@dc802804100637a589fabce1cb79ff13a1411302 # v6.2.0 + with: + images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }} + tags: | + type=semver,pattern={{version}} + type=semver,pattern={{major}}.{{minor}} + type=raw,value=latest,enable=${{ github.event_name == 'release' }} + type=raw,value=${{ inputs.tag }},enable=${{ github.event_name == 'workflow_dispatch' && inputs.tag != '' }} + type=raw,value=sha-${{ github.sha }},enable=${{ github.event_name == 'workflow_dispatch' && inputs.tag == '' }} + + - name: Build and push to the GitHub Container Registry + uses: docker/build-push-action@263435318d21b8e681c14492fe198d362a7d2c83 # v6.18.0 + with: + context: . + push: true + tags: ${{ steps.meta.outputs.tags }} + labels: ${{ steps.meta.outputs.labels }} + cache-from: type=gha,scope=ghcr + cache-to: type=gha,mode=max,scope=ghcr + + - name: Log in to Docker Hub + if: ${{ env.DOCKER_HUB_USERNAME != '' }} + uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0 + with: + username: ${{ env.DOCKER_HUB_USERNAME }} + password: ${{ env.DOCKER_HUB_PASSWORD }} + + - name: Extract Docker Hub metadata + id: meta-dockerhub + if: ${{ env.DOCKER_HUB_USERNAME != '' }} + uses: docker/metadata-action@dc802804100637a589fabce1cb79ff13a1411302 # v6.2.0 + with: + images: ${{ env.DOCKER_HUB_USERNAME }}/sbsim + tags: | + type=semver,pattern={{version}} + type=semver,pattern={{major}}.{{minor}} + type=raw,value=latest,enable=${{ github.event_name == 'release' }} + type=raw,value=${{ inputs.tag }},enable=${{ github.event_name == 'workflow_dispatch' && inputs.tag != '' }} + type=raw,value=sha-${{ github.sha }},enable=${{ github.event_name == 'workflow_dispatch' && inputs.tag == '' }} + + - name: Build and push to Docker Hub + if: ${{ env.DOCKER_HUB_USERNAME != '' }} + uses: docker/build-push-action@263435318d21b8e681c14492fe198d362a7d2c83 # v6.18.0 + with: + context: . + push: true + tags: ${{ steps.meta-dockerhub.outputs.tags }} + labels: ${{ steps.meta-dockerhub.outputs.labels }} + cache-from: type=gha,scope=dockerhub + cache-to: type=gha,mode=max,scope=dockerhub diff --git a/README.md b/README.md index 1da99b33..1b8ca545 100644 --- a/README.md +++ b/README.md @@ -54,6 +54,20 @@ instructions linked below. The [Setup Guide](docs/setup.md) provides all the information you need to run the code locally. +## Docker + +A container image is published to the GitHub Container Registry with each +release, so the notebooks and scripts can be run without installing the +dependencies locally: + +```bash +docker pull ghcr.io/google/sbsim:latest +docker run --rm -p 8888:8888 ghcr.io/google/sbsim:latest +``` + +The image starts a Jupyter notebook server on port 8888. For the local +development setup, see the [Setup Guide](docs/setup.md). + ## Contributing The [Contributor's Guide](docs/contributing.md) provides more information on how From a0ec5dc8c4a2050e38a9f98a71168600592b4b40 Mon Sep 17 00:00:00 2001 From: AARUSHGAUR Date: Thu, 29 Oct 2026 13:10:37 +0530 Subject: [PATCH 2/5] Move Docker guidance into the setup guide --- README.md | 13 ++------ docs/setup/docker.md | 75 ++++++++++++++++++++++++++++++++++---------- 2 files changed, 60 insertions(+), 28 deletions(-) diff --git a/README.md b/README.md index 1b8ca545..38816f05 100644 --- a/README.md +++ b/README.md @@ -56,17 +56,8 @@ the code locally. ## Docker -A container image is published to the GitHub Container Registry with each -release, so the notebooks and scripts can be run without installing the -dependencies locally: - -```bash -docker pull ghcr.io/google/sbsim:latest -docker run --rm -p 8888:8888 ghcr.io/google/sbsim:latest -``` - -The image starts a Jupyter notebook server on port 8888. For the local -development setup, see the [Setup Guide](docs/setup.md). +The [Docker Setup Guide](docs/setup/docker.md) explains how to run the image +published to the GitHub Container Registry or build the image locally. ## Contributing diff --git a/docs/setup/docker.md b/docs/setup/docker.md index 3bbbccec..4323cfd4 100644 --- a/docs/setup/docker.md +++ b/docs/setup/docker.md @@ -1,10 +1,61 @@ # Docker Setup Guide +The repository's `Dockerfile` defines a pre-configured environment +(`linux/amd64`) for running the notebooks and scripts without installing the +dependencies on the host machine. + +You can either run the image published to the GitHub Container Registry or build +the image locally from source. + +## Run the Published Image + +A container image is published to the GitHub Container Registry each time a +release is published. Pull the latest image: + +```bash +docker pull --platform linux/amd64 ghcr.io/google/sbsim:latest +``` + +Run the container: + +```bash +docker run -d \ + --name sbsim-container \ + --platform linux/amd64 \ + -p 8888:8888 \ + ghcr.io/google/sbsim:latest +``` + +The image starts a Jupyter notebook server on port 8888 with token +authentication disabled (as configured by the `Dockerfile`). Open your browser +at: + +``` +http://localhost:8888 +``` + +Images are tagged with `latest` and the release tag. For semantic version tags +(for example `v1.2.3`), the `1.2.3` and `1.2` tags are also published. Pin a +specific tag instead of `latest` when you need a reproducible environment: + +```bash +docker pull --platform linux/amd64 ghcr.io/google/sbsim:1.2.3 +``` + +> **Note:** The GitHub Container Registry package must be public for anonymous +> pulls. If it is private, authenticate first with `docker login ghcr.io` using +> a GitHub personal access token that has the `read:packages` scope. + +The `docker exec` and cleanup commands in the local build section below work the +same way for the published image. + +## Build the Image Locally + To get the repository set up on **non-Linux** environments (e.g. macOS on Apple Silicon), use the pre-configured Docker environment (`linux/amd64`) defined in the `Dockerfile`. -## 1. Prerequisites +### Prerequisites 1. **Docker Desktop**: Download and install from [docker.com](https://www.docker.com/products/docker-desktop). @@ -27,9 +78,7 @@ If `hello-world` succeeds, you're ready to proceed. > workloads may crash or hang due to resource constraints. For heavy TF > workloads, consider using a native Linux environment or cloud-based compute. -______________________________________________________________________ - -## 2. Build the Docker Image +### Build the Docker Image From the project root (where `Dockerfile` lives), run: @@ -51,9 +100,7 @@ Confirm the image exists: docker images sbsim:latest ``` -______________________________________________________________________ - -## 3. Run the Container in Detached Mode +### Run the Container in Detached Mode We recommend running the container _detached_ so you can open shells, run tests, and launch Jupyter without tying up your terminal: @@ -69,7 +116,7 @@ docker run -d \ > **Note:** This mounts your local code into `/workspace` in the container, > enabling live edits. -### 3.1 Access Jupyter +### Access Jupyter Open your browser at: @@ -84,9 +131,7 @@ deprecation warning for `NotebookApp.token`, you can instead use: jupyter notebook --no-browser --ServerApp.token='' ``` -______________________________________________________________________ - -## 4. Exec into the Running Container +### Exec into the Running Container To run commands inside the live container: @@ -122,9 +167,7 @@ docker exec sbsim-container poetry run pytest -q docker exec sbsim-container python --version ``` -______________________________________________________________________ - -## 5. Stop & Clean Up +### Stop and Clean Up ```bash # Stop the container @@ -137,9 +180,7 @@ docker rm sbsim-container docker rmi sbsim:latest ``` -______________________________________________________________________ - -## 6. Troubleshooting +### Troubleshooting - **Daemon not running**: If you see `Cannot connect to the Docker daemon`, open Docker Desktop or run: From 6215f281b437fcc589b473dc70c3471db81fc860 Mon Sep 17 00:00:00 2001 From: AARUSHGAUR Date: Thu, 29 Oct 2026 13:10:37 +0530 Subject: [PATCH 3/5] Document Docker publish workflow configuration --- .github/workflows/docker-publish.yaml | 62 ++++++++++++++++++++++++--- 1 file changed, 55 insertions(+), 7 deletions(-) diff --git a/.github/workflows/docker-publish.yaml b/.github/workflows/docker-publish.yaml index bb6b302c..285661a0 100644 --- a/.github/workflows/docker-publish.yaml +++ b/.github/workflows/docker-publish.yaml @@ -1,3 +1,49 @@ +# Publish the sbsim container image when a GitHub release is published. +# +# Required configuration +# ---------------------- +# No repository secrets are required for the GitHub Container Registry (GHCR) +# publish. The workflow authenticates with the automatically provided +# `GITHUB_TOKEN` and the `packages: write` permission declared below. +# +# Repository administrators should verify that Actions can create packages and +# that the published package is visible to end users. New packages are private +# by default; set `ghcr.io/google/sbsim` to public under the package settings if +# anonymous pulls should be allowed. See: +# - https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry +# - https://docs.github.com/en/packages/learn-github-packages/configuring-a-packages-access-control-and-visibility +# +# Optional Docker Hub publishing +# ------------------------------ +# To also publish `/sbsim` to Docker Hub, configure both repository +# secrets under Settings > Secrets and variables > Actions > Secrets: +# - DOCKER_HUB_USERNAME: Docker Hub username that owns the target repository. +# - DOCKER_HUB_PASSWORD: Docker Hub access token (not the account password) +# with permission to push to the target repository. +# If either secret is unset, the Docker Hub steps are skipped and only GHCR is +# published. See: +# - https://docs.docker.com/security/for-developers/access-tokens/ +# - https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions +# +# Workflow environment variables +# ------------------------------ +# - REGISTRY: registry host for the required GHCR publish (`ghcr.io`). +# - IMAGE_NAME: image path within the registry (`github.repository`, which is +# `google/sbsim` for this repository). +# - DOCKER_HUB_USERNAME and DOCKER_HUB_PASSWORD: optional secrets mapped to +# environment variables so the Docker Hub steps can be skipped when they are +# not configured. Values are masked by GitHub Actions and are never printed. +# +# Image tags +# ---------- +# - Release published: `latest`, the release tag, and, for semantic version +# tags such as `v1.2.3`, `1.2.3` and `1.2`. Non-semver release tags (for +# example `pre-sync-20250521`) still publish the release tag and `latest`. +# - Manual workflow run: the optional `tag` input, or `sha-` when no +# tag is provided. +# +# This workflow only reads repository contents and writes packages. It does not +# modify releases or any other repository state. name: Docker Publish on: @@ -28,6 +74,8 @@ jobs: steps: - name: Checkout code uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 + with: + persist-credentials: false - name: Set up Docker Buildx uses: docker/setup-buildx-action@e468171a9de216ec08956ac3ada2f0791b6bd435 # v3.11.1 @@ -45,11 +93,11 @@ jobs: with: images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }} tags: | + type=ref,event=tag,enable=${{ github.event_name == 'release' }} type=semver,pattern={{version}} type=semver,pattern={{major}}.{{minor}} - type=raw,value=latest,enable=${{ github.event_name == 'release' }} type=raw,value=${{ inputs.tag }},enable=${{ github.event_name == 'workflow_dispatch' && inputs.tag != '' }} - type=raw,value=sha-${{ github.sha }},enable=${{ github.event_name == 'workflow_dispatch' && inputs.tag == '' }} + type=sha,format=short,enable=${{ github.event_name == 'workflow_dispatch' && inputs.tag == '' }} - name: Build and push to the GitHub Container Registry uses: docker/build-push-action@263435318d21b8e681c14492fe198d362a7d2c83 # v6.18.0 @@ -62,7 +110,7 @@ jobs: cache-to: type=gha,mode=max,scope=ghcr - name: Log in to Docker Hub - if: ${{ env.DOCKER_HUB_USERNAME != '' }} + if: ${{ env.DOCKER_HUB_USERNAME != '' && env.DOCKER_HUB_PASSWORD != '' }} uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0 with: username: ${{ env.DOCKER_HUB_USERNAME }} @@ -70,19 +118,19 @@ jobs: - name: Extract Docker Hub metadata id: meta-dockerhub - if: ${{ env.DOCKER_HUB_USERNAME != '' }} + if: ${{ env.DOCKER_HUB_USERNAME != '' && env.DOCKER_HUB_PASSWORD != '' }} uses: docker/metadata-action@dc802804100637a589fabce1cb79ff13a1411302 # v6.2.0 with: images: ${{ env.DOCKER_HUB_USERNAME }}/sbsim tags: | + type=ref,event=tag,enable=${{ github.event_name == 'release' }} type=semver,pattern={{version}} type=semver,pattern={{major}}.{{minor}} - type=raw,value=latest,enable=${{ github.event_name == 'release' }} type=raw,value=${{ inputs.tag }},enable=${{ github.event_name == 'workflow_dispatch' && inputs.tag != '' }} - type=raw,value=sha-${{ github.sha }},enable=${{ github.event_name == 'workflow_dispatch' && inputs.tag == '' }} + type=sha,format=short,enable=${{ github.event_name == 'workflow_dispatch' && inputs.tag == '' }} - name: Build and push to Docker Hub - if: ${{ env.DOCKER_HUB_USERNAME != '' }} + if: ${{ env.DOCKER_HUB_USERNAME != '' && env.DOCKER_HUB_PASSWORD != '' }} uses: docker/build-push-action@263435318d21b8e681c14492fe198d362a7d2c83 # v6.18.0 with: context: . From e74eacb6919443058b5ca3d4ced50c816e4d84b1 Mon Sep 17 00:00:00 2001 From: AARUSHGAUR Date: Thu, 29 Oct 2026 13:11:28 +0530 Subject: [PATCH 4/5] Format README contributor note --- README.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index f40d0f60..7ad1731a 100644 --- a/README.md +++ b/README.md @@ -64,9 +64,10 @@ published to the GitHub Container Registry or build the image locally. The [Contributor's Guide](docs/contributing.md) provides more information on how to contribute to this repository. -We appreciate contributions and interest from the community! Please note that our -team maintains this repository alongside active internal Google project commitments, -so pull request reviews may take anywhere from a few days to a couple of weeks. -We review PRs as maintainer bandwidth allows. Thank you for your patience and support! +We appreciate contributions and interest from the community! Please note that +our team maintains this repository alongside active internal Google project +commitments, so pull request reviews may take anywhere from a few days to a +couple of weeks. We review PRs as maintainer bandwidth allows. Thank you for +your patience and support! ## [License](LICENSE) From d3a3007fc32f63989e8b8d9cbb98fc82b2ede573 Mon Sep 17 00:00:00 2001 From: AARUSHGAUR Date: Thu, 29 Oct 2026 13:12:58 +0530 Subject: [PATCH 5/5] Clarify published image usage and build platform --- .github/workflows/docker-publish.yaml | 2 ++ docs/setup/docker.md | 8 ++++++-- 2 files changed, 8 insertions(+), 2 deletions(-) diff --git a/.github/workflows/docker-publish.yaml b/.github/workflows/docker-publish.yaml index 285661a0..e3235a4e 100644 --- a/.github/workflows/docker-publish.yaml +++ b/.github/workflows/docker-publish.yaml @@ -103,6 +103,7 @@ jobs: uses: docker/build-push-action@263435318d21b8e681c14492fe198d362a7d2c83 # v6.18.0 with: context: . + platforms: linux/amd64 push: true tags: ${{ steps.meta.outputs.tags }} labels: ${{ steps.meta.outputs.labels }} @@ -134,6 +135,7 @@ jobs: uses: docker/build-push-action@263435318d21b8e681c14492fe198d362a7d2c83 # v6.18.0 with: context: . + platforms: linux/amd64 push: true tags: ${{ steps.meta-dockerhub.outputs.tags }} labels: ${{ steps.meta-dockerhub.outputs.labels }} diff --git a/docs/setup/docker.md b/docs/setup/docker.md index 4323cfd4..ee834708 100644 --- a/docs/setup/docker.md +++ b/docs/setup/docker.md @@ -9,6 +9,9 @@ the image locally from source. ## Run the Published Image +Docker Desktop or Docker Engine must be installed first; see +[Prerequisites](#prerequisites) below. + A container image is published to the GitHub Container Registry each time a release is published. Pull the latest image: @@ -46,8 +49,9 @@ docker pull --platform linux/amd64 ghcr.io/google/sbsim:1.2.3 > pulls. If it is private, authenticate first with `docker login ghcr.io` using > a GitHub personal access token that has the `read:packages` scope. -The `docker exec` and cleanup commands in the local build section below work the -same way for the published image. +To open a shell in the running container, use the same `docker exec` commands as +in the [local build section](#exec-into-the-running-container) below. To remove +the published image, run `docker rmi ghcr.io/google/sbsim:latest`. ## Build the Image Locally