From 4c6c4d7c8cf1197cf4964d4bf9948e48b2f8e130 Mon Sep 17 00:00:00 2001
From: Nick Ninov <n.ninov99@gmail.com>
Date: Mon, 29 Jun 2026 22:28:21 +0300
Subject: [PATCH] docker: Choose GitHub commit

---
 bot/utils.py        |  8 ++++++--
 docker-compose.yaml |  2 +-
 docs/utils.md       | 16 ++++++++++++++--
 3 files changed, 21 insertions(+), 5 deletions(-)

diff --git a/bot/utils.py b/bot/utils.py
index 7efbd9e..3cd5a3b 100644
--- a/bot/utils.py
+++ b/bot/utils.py
@@ -1,13 +1,15 @@
 import shutil, os, subprocess, sys, time
 from pathlib import Path
+from typing import Optional
 from .logger import Logger
 from . import exceptions
 
-def launch_docker_container(wait_seconds: int = 5):
+def launch_docker_container(commit: Optional[str] = None, wait_seconds: int = 5):
     """
     Launch the Status Backend Docker container using `docker-compose.yaml`
 
     Parameters:
+        - `commit` - the commit SHA. If no commit is provided, the latest version is pulled
         - `wait_seconds` - nunmber of seconds to wait before the code resumes. Sleep prevents calling `class Account` faster than launching the docker container. This only happens when the container already exists and it is must be turned on.
     """
     logger = Logger()
@@ -17,6 +19,7 @@ def launch_docker_container(wait_seconds: int = 5):
         raise exceptions.DockerError("Please install Docker.")
 
     logger.info(f"Running Docker on {platform}")
+    ref = commit if commit else "develop"
     DOCKER_COMPOSE_PATH = os.path.join(os.path.dirname(os.path.dirname(__file__)), "docker-compose.yaml")
     docker_path = DOCKER_COMPOSE_PATH
     if is_windows:
@@ -24,7 +27,8 @@ def launch_docker_container(wait_seconds: int = 5):
         drive = p.drive.rstrip(":").lower()
         docker_path = f"/mnt/{drive}/" + "/".join(p.parts[1:])
 
-    cmd = ["docker", "compose", "-f", docker_path, "up", "-d"]
+    cmd = ["env", f"STATUS_GO_REF={ref}", "docker", "compose", "-f", docker_path, "up", "-d", "--build"]
+
     if is_windows:
         if not shutil.which("wsl"):
             raise exceptions.DockerError("Please install wsl - https://learn.microsoft.com/en-us/windows/wsl/install.")
diff --git a/docker-compose.yaml b/docker-compose.yaml
index 806b081..da7c0e0 100644
--- a/docker-compose.yaml
+++ b/docker-compose.yaml
@@ -1,7 +1,7 @@
 services:
     backend:
         build:
-            context: https://github.com/status-im/status-go.git#develop
+            context: https://github.com/status-im/status-go.git#${STATUS_GO_REF:-develop}
         platform: linux/amd64
         container_name: status-backend
         ports:
diff --git a/docs/utils.md b/docs/utils.md
index b1b9729..6e5f75a 100644
--- a/docs/utils.md
+++ b/docs/utils.md
@@ -6,18 +6,30 @@ Helper functions for setting up the Status Backend environment.
 
 ## Methods
 
-### `launch_docker_container(wait_seconds=5)`
+### `launch_docker_container(commit=None, wait_seconds=5)`
 
-Launch Status Backend Docker container in the background using `docker-compose.yaml`. If `docker` is not installed, or if the container fails to start, an **exception will be raised** with the error message from Docker.
+Launch Status Backend Docker container in the background using `docker-compose.yaml`. If `docker` is not installed, or if the container fails to start, an **exception will be raised** with the error message from Docker. The container is built from [`status-im/status-go`](https://github.com/status-im/status-go) at the git ref you choose:
+
+```yaml
+context: https://github.com/status-im/status-go.git#${STATUS_GO_REF:-develop}
+```
+
+The image is always rebuilt (`docker compose up --build`) so a newly chosen `commit` is picked up instead of reusing a previously built image.
 
 | Name | Type | Required | Description |
 |-----|-----|-----|-------------|
+| `commit` | `str` | No | The `status-im/status-go` git ref to build from - a commit SHA, branch, or tag. When omitted, the latest `develop` branch is built. |
 | `wait_seconds` | `int` | No | Number of seconds to pause after the `docker compose up` command returns, giving Status Backend enough time to finish booting before subsequent code runs. Defaults to `5`. This matters mainly when the container already exists and is being restarted, because `docker compose up` returns immediately while the backend is still warming up - instantiating [`Account`](./account.md#accountdomainlocalhost-port8080-is_securefalse-backup_foldernone) too quickly will fail to connect. |
 
 ```python
 from bot import launch_docker_container
 
+# Build from the latest develop branch
 launch_docker_container(wait_seconds=10)
+
+# Pin a specific status-go commit
+# https://github.com/status-im/status-go/commit/2bee8b6a38cdc8f92d74e2dbb8c4e77fbbeea149
+launch_docker_container(commit="2bee8b6a38cdc8f92d74e2dbb8c4e77fbbeea149")
 ```
 
 **Windows Note**: In Docker go to `Settings > Resources > WSL integration` and make sure `Enable integration with my default WSL distro` and `Ubuntu` are **turned on**.