Merge pull request #110 from RedTeamSubnet/dev

documentation to clarify and streamline the process for building and publishing a miner solution as a Docker image.

Author: aliyuldashev

docs/miner/workflow/2.develop-solution.md

@@ -51,19 +51,19 @@ Start implementing your own solution for the chosen challenge. Refer to the chal
 
 Templates:
 
-- **Auto Browser Sniffer Challenge**: <https://github.com/RedTeamSubnet/ab-sniffer-challenge/tree/main/templates/commit>
-- **Anti-Detect Automation Challenge**: <https://github.com/RedTeamSubnet/ada-detection-challenge/tree/main/templates/commit>
-- **Humanize Behavior Challenge**: <https://github.com/RedTeamSubnet/humanize-behaviour-challenge/tree/main/templates/commit>
+- **Auto Browser Sniffer Challenge**: <https://github.com/RedTeamSubnet/ab-sniffer-challenge/tree/main/examples/miner_commit>
+- **Anti-Detect Automation Challenge**: <https://github.com/RedTeamSubnet/ada-detection-challenge/tree/main/examples/miner_commit>
+- **Humanize Behavior Challenge**: <https://github.com/RedTeamSubnet/humanize-behaviour-challenge/tree/main/examples/miner_commit>
 
-Navigate to the `templates/commit` directory in the cloned challenge repository to find the template structure for your solution as commit:
+Navigate to the `examples/miner_commit` directory in the cloned challenge repository to find the template structure for your solution as commit:
 
 ```sh
-cd ./templates/commit
+cd ./examples/miner_commit
 
 # Start developing your solution here
 ```
 
-Then implement your solution in there or copy that `templates/commit` directory to your working location as solution, you need that `commit` directory structure for submission later.
+Then implement your solution in there or copy that `examples/miner_commit` directory to your working location as solution, you need that `miner_commit` directory structure for submission later.
 
 ## 2.4. Test your solution against challenge
 

docs/miner/workflow/3.build-and-publish.md

@@ -5,72 +5,207 @@ tags: [build, submit, docker, commit, publish]
 
 # 3. 🏗 Build and Publish
 
-In this step, you will build your solution into a Docker image, publish it to Docker Hub, and obtain the SHA256 digest required for submission.
+In this step, you will build your solution into a Docker image, publish it to Docker Hub, and obtain the **SHA256 digest** required for submission.
+
+---
 
 ## Prerequisites
 
 - [**1. Preparation**](./1.preparation.md)
 - [**2. Develop Solution**](./2.develop-solution.md)
 
-## 3.1. Build docker image
+---
+
+## 3.1 Initialize & Start Environment
+
+!!! tip "Run First"
+    Before building your final image, ensure the environment is running correctly with the default template.
+
+    This confirms the connection between the **challenge container** and the **miner container**.
+
+### 1. Activate the Miner Service
+
+Copy the development compose override to the project root:
+
+~~~bash
+cp templates/compose/compose.override.dev.yml compose.override.yml
+~~~
+
+### 2. Start Services
+
+Run the compose helper script:
+
+~~~bash
+./compose.sh start
+~~~
+
+### 3. Confirm Execution
+
+Verify both services are running.
+
+Run:
+
+~~~bash
+docker ps -a
+~~~
+
+You should see two containers:
 
-This step assumes you've already cloned the challenge repository and implemented your solution in the `templates/commit` directory or in your working directory as mentioned in the [previous step](./2.develop-solution.md).
+- `challenge-api`
+- `miner-commit-api`
 
-!!! note "Arguments"
-    Make sure to replace the placeholders:
+---
+
+## 3.2 Configure & Build Miner Image
+
+You must **claim the miner image** by updating it with your own Docker Hub information and building it using the correct context.
 
-    - `<USERNAME>` with your Docker Hub username.
-    - `<REPO_NAME>` with your repository name on Docker Hub.
-    - `<VERSION>` with your version tag (e.g., `1.0.0`, `v1`, etc.).
+!!! danger "DO NOT BUILD FROM THE ROOT DIRECTORY"
+    Do **not** run the following command from the project root:
 
-    ```sh
-    docker build -t <USERNAME>/<REPO_NAME>:<VERSION> .
-    # For example:
-    docker build -t my_username/my_repo:1.0.0 .
+    ```bash
+    docker build .
     ```
 
-!!! danger "IMPORTANT"
-    To prevent submission theft, please don't include the challenge name or your Discord username in the image name. This precaution is necessary because multiple miners can locate your image on Docker Hub and submit it on your behalf.
+    This will either fail or build the wrong image.
 
-## 3.2. Publish docker image
+    Always build through **Docker Compose**, which ensures the correct build context:
 
-### 3.2.1. Create Docker Hub account
+    ```
+    cd ./examples/miner_commit
+    ```
+
+    ```bash
+    docker compose build miner-commit-api
+    ```
+
+---
 
-Sign up at <https://hub.docker.com>, if you don't have an account yet.
+=== "Step 1 — Update compose.override.yml"
 
-### 3.2.2. Docker Login
+    Locate the `miner-commit-api` service and update the **image field** to your Docker Hub repository.
 
-You need to login using your Docker Hub credentials before pushing the image:
+    !!! warning "Crucial: Do Not Edit Challenge API"
+        Only modify the **image field under `miner-commit-api`**.
+
+        Do **not** change anything inside the `challenge-api` service.
+
+    ```yaml
+    miner-commit-api:
+      # CHANGE THIS to your Docker Hub repository
+      image: <USERNAME>/<REPO_NAME>:<VERSION>
+
+      # DO NOT CHANGE THIS (points to your solution code)
+      build:
+        context: ./examples/miner_commit
+    ```
+
+=== "Step 2 — Build Miner Image"
+
+    Build **only the miner container**:
+
+    ```bash
+    docker compose build miner-commit-api
+    ```
 
-```sh
+    This builds your solution container using the correct directory.
+
+    !!! danger "Prevent Submission Theft"
+        Do **not** include the challenge name or your Discord username in the image name.
+
+        Other miners can scan Docker Hub and submit your image on your behalf.
+
+## 3.3 Verify Locally (Sanity Check)
+
+Before publishing your image, confirm that the container is running with **your custom image name**.
+
+### 1. Restart Services
+
+~~~bash
+./compose.sh restart
+~~~
+
+### 2. Verify the Image
+
+Run:
+
+~~~bash
+docker ps -a
+~~~
+
+Check the **IMAGE** column for the miner container.
+
+!!! success "Correct"
+    `miner-commit-api` shows:
+
+    **`<USERNAME>/<REPO_NAME>:<VERSION>`**
+
+!!! failure "Wrong"
+    It shows:
+
+    **`redteamsubnet61/rest-my-challenge`**
+
+    This means you are accidentally running the **challenge image** instead of your **miner solution**.
+
+---
+
+## 3.4 Publish Docker Image
+
+### 3.4.1 Create Docker Hub Account
+
+Create an account if you do not already have one:
+
+<https://hub.docker.com>
+
+### 3.4.2 Docker Login
+
+Authenticate with Docker Hub:
+
+~~~bash
 docker login
-```
+~~~
+
+### 3.4.3 Push Docker Image
 
-### 3.2.3. Push docker image to Docker Hub
+Push your image to Docker Hub:
 
-```sh
+~~~bash
 docker push <USERNAME>/<REPO_NAME>:<VERSION>
-# For example:
+~~~
+
+Example:
+
+~~~bash
 docker push my_username/my_repo:1.0.0
-```
+~~~
 
-### 3.2.4. Get SHA256 digest as commit hash
+### 3.4.4 Get SHA256 Digest (Commit Hash)
 
 !!! warning "FOR SUBMISSION"
-    Save the SHA256 digest of your pushed docker image, which is required for submission for **miner commit hash**!
+    Save the **SHA256 digest** of your pushed Docker image.
+
+    This value is required as your **miner commit hash** when submitting your solution.
+
+Run:
 
-```sh
+~~~bash
 docker inspect --format='{{index .RepoDigests 0}}' <USERNAME>/<REPO_NAME>:<VERSION>
-# For example:
+~~~
+
+Example:
+
+~~~bash
 docker inspect --format='{{index .RepoDigests 0}}' my_username/my_repo:1.0.0
-```
+~~~
 
-Output:
+Example output:
 
-```sh
+~~~
 my_username/my_repo@sha256:abc123def456...
-```
+~~~
+
+---
 
-## Next step
+## Next Step
 
 - [**4. Submit Commit**](./4.submit-commit.md)