From c6cbea54510353eae38226d5110f5c3d5076f05f Mon Sep 17 00:00:00 2001 From: abdibekbolot Date: Sat, 14 Mar 2026 16:48:54 +0900 Subject: [PATCH] docs: update development workflow documentation for clarity and accuracy --- docs/miner/workflow/2.develop-solution.md | 12 +- docs/miner/workflow/3.build-and-publish.md | 203 +++++++++++++++++---- 2 files changed, 175 insertions(+), 40 deletions(-) diff --git a/docs/miner/workflow/2.develop-solution.md b/docs/miner/workflow/2.develop-solution.md index fd5eb999..1497dbc3 100644 --- a/docs/miner/workflow/2.develop-solution.md +++ b/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**: -- **Anti-Detect Automation Challenge**: -- **Humanize Behavior Challenge**: +- **Auto Browser Sniffer Challenge**: +- **Anti-Detect Automation Challenge**: +- **Humanize Behavior Challenge**: -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 diff --git a/docs/miner/workflow/3.build-and-publish.md b/docs/miner/workflow/3.build-and-publish.md index 38166d01..ea5e7641 100644 --- a/docs/miner/workflow/3.build-and-publish.md +++ b/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. - - `` with your Docker Hub username. - - `` with your repository name on Docker Hub. - - `` 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 /: . - # 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 , 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: /: + + # 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: + + **`/:`** + +!!! 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: + + + +### 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 /: -# 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}}' /: -# 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)