Merge pull request #1346 from o1-labs/dw/clean-documentation-docker

Improve documentation for the docker usage

Author: dannywillems

.github/actions/push-docker-manifest/action.yml

@@ -16,6 +16,9 @@ inputs:
   dockerhub_token:
     description: 'Docker Hub token'
     required: true
+  additional_tags:
+    description: 'Additional tags to create (comma-separated, optional)'
+    required: false
 
 runs:
   using: 'composite'
@@ -40,6 +43,20 @@ runs:
       shell: bash
       working-directory: /tmp/digests
       run: |
+        # Build primary tag
+        TAGS="--tag ${{ inputs.registry_image }}:${{ inputs.git_commit }}"
+
+        # Add additional tags if provided
+        if [[ -n "${{ inputs.additional_tags }}" ]]; then
+          IFS=',' read -ra ADDITIONAL_TAGS <<< "${{ inputs.additional_tags }}"
+          for tag in "${ADDITIONAL_TAGS[@]}"; do
+            tag=$(echo "$tag" | xargs)  # trim whitespace
+            if [[ -n "$tag" ]]; then
+              TAGS="$TAGS --tag ${{ inputs.registry_image }}:$tag"
+            fi
+          done
+        fi
+
         docker buildx imagetools create \
-          --tag ${{ inputs.registry_image }}:${{ inputs.git_commit }} \
-          $(printf '${{ inputs.registry_image }}@sha256:%s ' *)
+          $TAGS \
+          $(printf '${{ inputs.registry_image }}@sha256:%s ' *)

.github/workflows/docker.yaml

@@ -33,7 +33,6 @@ jobs:
           git fetch --depth=1 origin +refs/tags/*:refs/tags/*
 
       - name: Login to Docker Hub
-        if: github.ref == 'refs/heads/develop' || startsWith(github.ref, 'refs/tags/') || startsWith(github.ref, 'refs/heads/release')
         uses: docker/login-action@v3
         with:
           username: ${{ secrets.DOCKERHUB_USERNAME }}
@@ -89,7 +88,6 @@ jobs:
         uses: actions/checkout@v5
 
       - name: Login to Docker Hub
-        if: github.ref == 'refs/heads/develop' || startsWith(github.ref, 'refs/tags/') || startsWith(github.ref, 'refs/heads/release')
         uses: docker/login-action@v3
         with:
           username: ${{ secrets.DOCKERHUB_USERNAME }}
@@ -138,11 +136,14 @@ jobs:
         run: |
           if [[ "${{ github.ref }}" == "refs/heads/develop" ]]; then
             echo "GIT_COMMIT=${GITHUB_SHA:0:8}" >> $GITHUB_ENV
+            echo "ADDITIONAL_TAGS=develop" >> $GITHUB_ENV
           elif [[ "${{ github.ref }}" == refs/tags/* ]]; then
             echo "GIT_COMMIT=${GITHUB_REF#refs/tags/}" >> $GITHUB_ENV
+            echo "ADDITIONAL_TAGS=" >> $GITHUB_ENV
           elif [[ "${{ github.ref }}" == refs/heads/release/* ]]; then
             BRANCH_NAME="${GITHUB_REF#refs/heads/}"
             echo "GIT_COMMIT=${BRANCH_NAME}" >> $GITHUB_ENV
+            echo "ADDITIONAL_TAGS=" >> $GITHUB_ENV
           fi
 
       - name: Push frontend multi-arch manifest
@@ -153,6 +154,7 @@ jobs:
           digest_pattern: 'frontend-*-digests-*'
           dockerhub_username: ${{ secrets.DOCKERHUB_USERNAME }}
           dockerhub_token: ${{ secrets.DOCKERHUB_TOKEN }}
+          additional_tags: ${{ env.ADDITIONAL_TAGS }}
 
   # Push node multi-arch manifest (after node build completes)
   push-node-image:
@@ -168,11 +170,14 @@ jobs:
         run: |
           if [[ "${{ github.ref }}" == "refs/heads/develop" ]]; then
             echo "GIT_COMMIT=${GITHUB_SHA:0:8}" >> $GITHUB_ENV
+            echo "ADDITIONAL_TAGS=develop" >> $GITHUB_ENV
           elif [[ "${{ github.ref }}" == refs/tags/* ]]; then
             echo "GIT_COMMIT=${GITHUB_REF#refs/tags/}" >> $GITHUB_ENV
+            echo "ADDITIONAL_TAGS=" >> $GITHUB_ENV
           elif [[ "${{ github.ref }}" == refs/heads/release/* ]]; then
             BRANCH_NAME="${GITHUB_REF#refs/heads/}"
             echo "GIT_COMMIT=${BRANCH_NAME}" >> $GITHUB_ENV
+            echo "ADDITIONAL_TAGS=" >> $GITHUB_ENV
           fi
 
       - name: Push node multi-arch manifest
@@ -183,3 +188,4 @@ jobs:
           digest_pattern: 'node-digests-*'
           dockerhub_username: ${{ secrets.DOCKERHUB_USERNAME }}
           dockerhub_token: ${{ secrets.DOCKERHUB_TOKEN }}
+          additional_tags: ${{ env.ADDITIONAL_TAGS }}

.gitignore

@@ -18,4 +18,5 @@ website/static/api-docs/
 ledger/3.0.0devnet
 ledger/3.0.0mainnet
 ledger/3.0.1devnet
-ledger/berkeley_rc1
+ledger/berkeley_rc1
+mina-workdir

docker-compose.archive.devnet.yml

@@ -61,7 +61,7 @@ services:
       - "127.0.0.1:3086:3086"
 
   mina-rust-node:
-    image: openmina/openmina:latest
+    image: o1labs/mina-rust:${MINA_RUST_TAG:-latest}
     container_name: mina-rust-node
     environment:
       - MINA_ARCHIVE_ADDRESS=http://archive-mina-rust:3086

docker-compose.block-producer.yml

@@ -1,8 +1,15 @@
 services:
   mina-node:
-    image: openmina/openmina:${MINA_TAG:-latest}
-    entrypoint: >
-      sh -c "mina node --producer-key /root/.mina/producer-key $${COINBASE_RECEIVER:+--coinbase-receiver $$COINBASE_RECEIVER} $${MINA_LIBP2P_EXTERNAL_IP:+--libp2p-external-ip $$MINA_LIBP2P_EXTERNAL_IP} $${MINA_LIBP2P_PORT:+--libp2p-port $$MINA_LIBP2P_PORT}"
+    image: o1labs/mina-rust:${MINA_RUST_TAG:-latest}
+    entrypoint: ["/bin/sh", "-c"]
+    command: >
+      "
+      ARGS='node --producer-key /root/.mina/producer-key';
+      if [ -n \"$$COINBASE_RECEIVER\" ]; then ARGS=\"$$ARGS --coinbase-receiver $$COINBASE_RECEIVER\"; fi;
+      if [ -n \"$$MINA_LIBP2P_EXTERNAL_IP\" ]; then ARGS=\"$$ARGS --libp2p-external-ip $$MINA_LIBP2P_EXTERNAL_IP\"; fi;
+      if [ -n \"$$MINA_LIBP2P_PORT\" ]; then ARGS=\"$$ARGS --libp2p-port $$MINA_LIBP2P_PORT\"; fi;
+      exec mina $$ARGS
+      "
     ports:
       - "3000:3000"
       - "${MINA_LIBP2P_PORT:-8302}:${MINA_LIBP2P_PORT:-8302}"
@@ -11,12 +18,12 @@ services:
     environment:
       MINA_PRIVKEY_PASS: "${MINA_PRIVKEY_PASS:-}"
       COINBASE_RECEIVER: "${COINBASE_RECEIVER:-}"
-      MINA_LIBP2P_EXTERNAL_IP: "${MINA_LIBP2P_EXTERNAL_IP}"
-      MINA_LIBP2P_PORT: "${MINA_LIBP2P_PORT}"
+      MINA_LIBP2P_EXTERNAL_IP: "${MINA_LIBP2P_EXTERNAL_IP:-}"
+      MINA_LIBP2P_PORT: "${MINA_LIBP2P_PORT:-8302}"
 
   frontend:
-    image: openmina/frontend:${MINA_FRONTEND_TAG:-latest}
+    image: o1labs/mina-rust-frontend:${MINA_FRONTEND_TAG:-latest}
     environment:
       MINA_FRONTEND_ENVIRONMENT: compose-producer
     ports:
-      - "8070:80"
+      - "8070:8070"

docker-compose.local.producers.yml

@@ -1,7 +1,7 @@
 services:
   local-producer-cluster:
     container_name: local-producer-cluster
-    image: openmina/openmina:0.16.0
+    image: o1labs/mina-rust:${MINA_RUST_TAG:-latest}
     environment:
       - RUST_BACKTRACE=1
     entrypoint: ["openmina-node-testing", "scenarios-generate", "--name", "simulation-small-forever-real-time"]
@@ -12,8 +12,8 @@ services:
 
   frontend:
     container_name: frontend
-    image: openmina/frontend:0.16.0
+    image: o1labs/mina-rust-frontend:${MINA_FRONTEND_TAG:-latest}
     environment:
       MINA_FRONTEND_ENVIRONMENT: block-producers
     ports:
-      - "8070:80"
+      - "8070:8070"

docker-compose.yml

@@ -1,20 +1,25 @@
 services:
   mina-node:
-    image: openmina/openmina:${MINA_TAG:-latest}
-    entrypoint: >
-      sh -c "mina node $${MINA_LIBP2P_EXTERNAL_IP:+--libp2p-external-ip $$MINA_LIBP2P_EXTERNAL_IP} $${MINA_LIBP2P_PORT:+--libp2p-port $$MINA_LIBP2P_PORT}"
+    image: o1labs/mina-rust:${MINA_RUST_TAG:-latest}
+    entrypoint: ["/bin/sh", "-c"]
+    command: >
+      "
+      ARGS='node --network devnet';
+      if [ -n \"$$MINA_LIBP2P_EXTERNAL_IP\" ]; then ARGS=\"$$ARGS --libp2p-external-ip $$MINA_LIBP2P_EXTERNAL_IP\"; fi;
+      if [ -n \"$$MINA_LIBP2P_PORT\" ]; then ARGS=\"$$ARGS --libp2p-port $$MINA_LIBP2P_PORT\"; fi;
+      exec mina $$ARGS
+      "
     volumes:
       - ./mina-workdir:/root/.mina:rw
     ports:
-      - "3000:3000"
       - "${MINA_LIBP2P_PORT:-8302}:${MINA_LIBP2P_PORT:-8302}"
     environment:
-      MINA_LIBP2P_EXTERNAL_IP: "${MINA_LIBP2P_EXTERNAL_IP}"
-      MINA_LIBP2P_PORT: "${MINA_LIBP2P_PORT}"
+      MINA_LIBP2P_EXTERNAL_IP: "${MINA_LIBP2P_EXTERNAL_IP:-}"
+      MINA_LIBP2P_PORT: "${MINA_LIBP2P_PORT:-8302}"
 
   frontend:
-    image: openmina/frontend:${MINA_FRONTEND_TAG:-latest}
+    image: o1labs/mina-rust-frontend:${MINA_FRONTEND_TAG:-latest}
     environment:
       MINA_FRONTEND_ENVIRONMENT: compose
     ports:
-      - "8070:80"
+      - "8070:8070"

website/docs/developers/docker-images.md

@@ -13,6 +13,20 @@ The Mina Rust project provides Docker images for easy deployment and testing.
 
 Docker images are available at Docker Hub under the `o1labs` organization:
 
+<!-- prettier-ignore-start -->
+
+:::warning Deprecated Repository
+
+Docker images from the
+[openmina/openmina](https://hub.docker.com/r/openmina/openmina) repository are
+deprecated. Please use the
+[o1labs/mina-rust](https://hub.docker.com/r/o1labs/mina-rust) images instead for
+the latest updates and support.
+
+:::
+
+<!-- prettier-ignore-stop -->
+
 - **Main Node**: `o1labs/mina-rust` - The core Mina Rust node
 - **Frontend**: `o1labs/mina-rust-frontend` - Web dashboard and monitoring
   interface
@@ -40,12 +54,40 @@ docker pull o1labs/mina-rust:2b9e87b2
 docker pull o1labs/mina-rust-frontend:2b9e87b2
 ```
 
+### For Development and Testing
+
+For accessing the latest development features, use the `develop` tag:
+
+<!-- prettier-ignore-start -->
+
+:::warning Unstable Development Version
+
+The `develop` tag points to the latest code from the development branch and may
+be unstable. Only use this for development, testing, or accessing the newest
+features. For production use, always use version tags.
+
+:::
+
+<!-- prettier-ignore-stop -->
+
+```bash
+# Latest development version (unstable)
+docker pull o1labs/mina-rust:develop
+docker pull o1labs/mina-rust-frontend:develop
+```
+
+### Latest Tag
+
+The `latest` tag always corresponds to the latest commit on the main branch,
+which represents the current stable release state.
+
 ### Automatic Publishing
 
 Images are automatically built and pushed to Docker Hub:
 
 - **On develop branch**: When commits are pushed to `develop`, images are tagged
-  with the commit hash (8 characters)
+  with the commit hash (8 characters) and also tagged as `develop` for easy
+  access to the latest development version
 - **On release branches**: When commits are pushed to branches starting with
   `release/`, images are tagged with the branch name (e.g., `release/v1.5.0`) -
   useful for testing release candidates
@@ -59,6 +101,22 @@ You can find available tags at:
 - [o1labs/mina-rust on Docker Hub](https://hub.docker.com/r/o1labs/mina-rust/tags)
 - [o1labs/mina-rust-frontend on Docker Hub](https://hub.docker.com/r/o1labs/mina-rust-frontend/tags)
 
+## Quick Start with Docker Compose
+
+The easiest way to get started is using the provided docker compose
+configuration:
+
+```bash
+# Clone the repository
+git clone https://github.com/o1-labs/mina-rust.git
+cd mina-rust
+
+# Start node and frontend
+docker compose up -d
+
+# Access the frontend at http://localhost:8070
+```
+
 ## Local Development
 
 For local development and testing, you can build images using the Makefile:
@@ -103,36 +161,9 @@ docker pull o1labs/mina-rust:latest
   emulation
 - **Faster startup**: Native images start faster than emulated ones
 
-### Verifying Architecture
-
-You can verify which architecture you're running:
-
-```bash
-docker run --rm o1labs/mina-rust:latest uname -m
-# x86_64 on Intel/AMD systems
-# aarch64 on ARM systems
-```
-
-## Using Docker Images
+## For Node Operators
 
-### Running a Basic Node
-
-```bash
-# Pull and run the main node
-docker pull o1labs/mina-rust:latest
-docker run -p 8302:8302 o1labs/mina-rust:latest
-```
-
-### Running with Frontend Dashboard
-
-```bash
-# Using Docker Compose (recommended)
-# Download the latest release and use the provided docker-compose files
-
-# Or run containers separately
-docker run -d --name mina-node -p 8302:8302 o1labs/mina-rust:latest
-docker run -d --name mina-frontend -p 8070:8070 o1labs/mina-rust-frontend:latest
-```
+For detailed usage instructions including running block producers, archive
+nodes, and configuration examples, see:
 
-For complete setup guides, see the
-[Node Operators](../node-operators/getting-started) section.
+[→ Node Operators Docker Usage Guide](../node-operators/docker-usage)