Add GHCR compose, CI smoke test, and docs

SunOner · SunOner · commit b1ca00a9b235 · 2026-06-07T21:42:40.000+03:00
Add docker-compose.ghcr.yml to run the published GitHub Container Registry image and introduce LABELIMG_IMAGE_TAG in .env.example to control image tag. Update README with instructions for using the prebuilt GHCR image and clarify local build steps. Enhance CI (/.github/workflows/docker.yml) to build a test image, run a smoke test that checks the /api/health and root page, and adjust build/push tagging (including latest for default branch) and cache settings. Add .gitkeep files for data and models/plugins and update .gitignore to ignore plugin files while preserving the .gitkeep placeholders.
diff --git a/.env.example b/.env.example
@@ -1,2 +1,3 @@
 LABELIMG_PORT=8000
 LABELIMG_DATASETS_DIR=./datasets
+LABELIMG_IMAGE_TAG=main
diff --git a/.github/workflows/docker.yml b/.github/workflows/docker.yml
@@ -41,17 +41,52 @@ jobs:
         with:
           images: ${{ env.IMAGE_NAME }}
           tags: |
+            type=raw,value=latest,enable={{is_default_branch}}
             type=ref,event=branch
             type=ref,event=pr
             type=semver,pattern={{version}}
             type=semver,pattern={{major}}.{{minor}}
             type=sha
 
+      - name: Build image for smoke test
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          load: true
+          tags: labelimg-next:ci
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+
+      - name: Smoke test image
+        run: |
+          set -euo pipefail
+
+          container_id="$(docker run --rm -d -p 127.0.0.1:18000:8000 labelimg-next:ci)"
+
+          cleanup() {
+            docker rm -f "$container_id" >/dev/null 2>&1 || true
+          }
+          trap cleanup EXIT
+
+          for attempt in {1..30}; do
+            if curl -fsS http://127.0.0.1:18000/api/health >/tmp/labelimg-health.json; then
+              grep -q '"status":"ok"' /tmp/labelimg-health.json
+              curl -fsS http://127.0.0.1:18000/ >/tmp/labelimg-index.html
+              grep -qi '<!doctype html' /tmp/labelimg-index.html
+              exit 0
+            fi
+            sleep 1
+          done
+
+          docker logs "$container_id"
+          exit 1
+
       - name: Build and publish image
+        if: github.event_name != 'pull_request'
         uses: docker/build-push-action@v6
         with:
           context: .
-          push: ${{ github.event_name != 'pull_request' }}
+          push: true
           tags: ${{ steps.meta.outputs.tags }}
           labels: ${{ steps.meta.outputs.labels }}
           cache-from: type=gha
diff --git a/.gitignore b/.gitignore
@@ -50,6 +50,7 @@ tmp.*
 ehthumbs.db
 Thumbs.db
 /data/plugin-runtime-sources
-/models/plugins
+/models/plugins/*
+!/models/plugins/.gitkeep
 /datasets/*
 !/datasets/.gitkeep
diff --git a/README.md b/README.md
@@ -4,22 +4,59 @@
 
 ## Start
 
-### Docker
+### Docker: prebuilt image
+
+Use the published GitHub Container Registry image when you only want to run the
+app and do not need to rebuild it from source.
+
+```bash
+git clone https://github.com/SunOner/react_labelimg.git
+cd react_labelimg
+cp .env.example .env
+docker compose -f docker-compose.ghcr.yml pull
+docker compose -f docker-compose.ghcr.yml up
+```
+
+On Windows PowerShell:
+
+```powershell
+git clone https://github.com/SunOner/react_labelimg.git
+cd react_labelimg
+Copy-Item .env.example .env
+docker compose -f docker-compose.ghcr.yml pull
+docker compose -f docker-compose.ghcr.yml up
+```
+
+The default image tag is `main`:
+
+```bash
+ghcr.io/sunoner/react_labelimg:main
+```
+
+The Docker workflow publishes `main` and `latest` for default branch builds.
+Tagged releases such as `v0.1.0` publish version tags such as `0.1.0` and
+`0.1`.
+
+### Docker: build from source
 
 Docker is the simplest way to run the app on Windows and Ubuntu. It builds the
 React frontend, installs the FastAPI backend dependencies and serves everything
 from one container.
 
-Copy the example environment file and set the host folder that contains your
-images:
+Clone the repository, copy the example environment file and set the host folder
+that contains your images:
 
 ```bash
+git clone https://github.com/SunOner/react_labelimg.git
+cd react_labelimg
 cp .env.example .env
 ```
 
 On Windows PowerShell:
 
 ```powershell
+git clone https://github.com/SunOner/react_labelimg.git
+cd react_labelimg
 Copy-Item .env.example .env
 ```
 
@@ -51,15 +88,12 @@ Stop the app:
 docker compose down
 ```
 
-Build a release image manually:
+Build a local image manually:
 
 ```bash
-docker build -t labelimg-next:0.1.0 .
+docker build -t labelimg-next:local .
 ```
 
-Tagged GitHub releases such as `v0.1.0` are also built by the Docker workflow
-and published to GitHub Container Registry as `ghcr.io/<owner>/<repo>:0.1.0`.
-
 ### Local Python/Node
 
 On Windows, run the project from inside WSL (WSL2 recommended). Open a WSL
diff --git a/data/.gitkeep b/data/.gitkeep
@@ -0,0 +1 @@
+
diff --git a/docker-compose.ghcr.yml b/docker-compose.ghcr.yml
@@ -0,0 +1,19 @@
+services:
+  labelimg-next:
+    image: ghcr.io/sunoner/react_labelimg:${LABELIMG_IMAGE_TAG:-main}
+    pull_policy: always
+    ports:
+      - "${LABELIMG_PORT:-8000}:8000"
+    environment:
+      LABELIMG_DISABLE_FILE_DIALOGS: "1"
+    volumes:
+      - type: bind
+        source: ./data
+        target: /app/data
+      - type: bind
+        source: ./models/plugins
+        target: /app/models/plugins
+      - type: bind
+        source: ${LABELIMG_DATASETS_DIR:-./datasets}
+        target: /datasets
+    restart: unless-stopped
diff --git a/models/plugins/.gitkeep b/models/plugins/.gitkeep
@@ -0,0 +1 @@
+

Original file line number	Diff line number	Diff line change
`@@ -1,2 +1,3 @@`
`1`	`1`	`LABELIMG_PORT=8000`
`2`	`2`	`LABELIMG_DATASETS_DIR=./datasets`
	`3`	`+LABELIMG_IMAGE_TAG=main`