External/SnapOtter
1
0
Fork 0
mirror of https://github.com/snapotter-hq/SnapOtter.git synced 2026-08-03 07:46:42 +02:00
Code Issues Packages Projects Releases Wiki Activity

docs: update for unified Docker image

Browse Source 
Rewrite docker-tags.md for single image with GPU auto-detection.
Update deployment.md to remove variant table and lite/cuda references.
Replace LaMa Cleaner references with OpenCV in architecture and AI docs.
Add migration notes for users on :lite and :cuda tags.
This commit is contained in:
Siddharth Kumar Sah
2026-04-10 00:25:28 +08:00
parent b385a2eabb
commit ff37bb769a
4 changed files with 49 additions and 104 deletions
Download Patch File Download Diff File Expand all files Collapse all files
apps/docs/api/ai.md
+2 -6
View File
@@ -4,12 +4,8 @@ The `@stirling-image/ai` package wraps Python ML models in TypeScript functions.
All model weights are bundled in the Docker image during the build. No downloads happen at runtime.
::: warning Lite image
AI tools are not available in the `:lite` Docker image. The API returns `501 Not Available` for these endpoints when running the lite variant. Use `:latest` for AI features. See [Docker Tags](/guide/docker-tags) for details.
:::
::: tip GPU acceleration
The `:cuda` Docker image includes GPU-accelerated versions of the ML libraries. Background removal, upscaling, and OCR all benefit from NVIDIA GPU acceleration. The image auto-detects your GPU and falls back to CPU if none is available. See [Docker Tags](/guide/docker-tags) for setup.
The Docker image includes CUDA-accelerated ML libraries on amd64. Add `--gpus all` to your Docker run command to enable GPU acceleration. The image auto-detects your GPU and falls back to CPU if none is available.
:::
## Background removal
@@ -73,7 +69,7 @@ Returns the blurred image along with metadata about each detected face region (b
Removes objects from images by filling in the area with generated content that matches the surroundings.
**Model:** [LaMa](https://github.com/advimman/lama) (Large Mask Inpainting)
**Model:** OpenCV TELEA algorithm
Takes an image and a mask (white = area to erase, black = keep). Returns the inpainted image.
apps/docs/guide/architecture.md
+1 -1
View File
@@ -34,7 +34,7 @@ Supported operations:
- **Upscaling** -- RealESRGAN
- **OCR** -- PaddleOCR
- **Face detection/blurring** -- MediaPipe
- **Object erasing (inpainting)** -- LaMa Cleaner
- **Object erasing (inpainting)** -- OpenCV
Python scripts live in `packages/ai/python/`. The Docker image pre-downloads all model weights during the build so the container works offline.
apps/docs/guide/deployment.md
+6 -14
View File
@@ -1,16 +1,8 @@
# Deployment
Stirling Image ships as a single Docker container. The image supports **linux/amd64** and **linux/arm64**, so it runs natively on Intel/AMD servers, Apple Silicon Macs, and ARM devices like the Raspberry Pi 4/5.
Stirling Image ships as a single Docker container. The image supports **linux/amd64** (with NVIDIA CUDA) and **linux/arm64** (CPU), so it runs natively on Intel/AMD servers, Apple Silicon Macs, and ARM devices like the Raspberry Pi 4/5.
Three variants are available:
| Variant | Tag | Size | What's included |
|---------|-----|------|-----------------|
| Full | `:latest` | ~11 GB | All tools + AI/ML (background removal, upscaling, OCR, face blur, object eraser) |
| Lite | `:lite` | ~1.5 GB | All image processing tools, no AI/ML |
| CUDA | `:cuda` | ~14 GB | Full + GPU-accelerated AI (NVIDIA only, amd64) |
See [Docker Tags](./docker-tags) for the full comparison, Docker Compose examples, and version pinning.
See [Docker Image](./docker-tags) for GPU setup, Docker Compose examples, and version pinning.
## Docker Compose (recommended)
@@ -64,14 +56,14 @@ Everything runs from a single process. The Fastify server handles API requests a
- RealESRGAN (upscaling)
- PaddleOCR (text recognition)
- MediaPipe (face detection)
- LaMa Cleaner (inpainting/object removal)
- OpenCV (inpainting/object removal)
- onnxruntime, opencv-python, Pillow, numpy
Model weights are downloaded at build time, so the container works fully offline. The lite image (`:lite`) skips all Python packages and model downloads.
Model weights are downloaded at build time, so the container works fully offline.
### Architecture notes
All core image tools (resize, crop, compress, convert, watermark, etc.) work on both amd64 and arm64. Some ML packages (PaddleOCR, MediaPipe, LaMa Cleaner) have limited arm64 support and may be unavailable on ARM systems. The container logs a warning for any package that could not be installed and falls back gracefully — Tesseract handles OCR and Lanczos handles upscaling when the ML alternatives are missing.
All tools work on both amd64 and arm64. AI tools (background removal, upscaling, OCR, face detection) use CUDA-accelerated packages on amd64 and CPU packages on arm64. GPU acceleration is auto-detected at runtime when `--gpus all` is passed.
## Volumes
@@ -120,7 +112,7 @@ Set `client_max_body_size` to match your `MAX_UPLOAD_SIZE_MB` value.
The GitHub repository has two workflows:
- **release.yml** -- On release, builds multi-arch Docker images (amd64 + arm64) for both the full and lite variants, and pushes to Docker Hub (`stirlingimage/stirling-image`) and GitHub Container Registry (`ghcr.io/stirling-image/stirling-image`).
- **release.yml** -- On release, builds a multi-arch Docker image (amd64 + arm64), and pushes to Docker Hub (`stirlingimage/stirling-image`) and GitHub Container Registry (`ghcr.io/stirling-image/stirling-image`).
- **deploy-docs.yml** -- Builds this documentation site and deploys it to GitHub Pages.
Both run automatically. No manual steps needed after merging to `main`.
apps/docs/guide/docker-tags.md
+40 -83
View File
@@ -1,53 +1,28 @@
# Docker Image Tags
# Docker Image
Stirling Image ships three Docker image variants to fit different use cases.
Stirling Image ships as a single Docker image that works on all platforms.
## Full (default)
## Quick start
```bash
docker pull stirlingimage/stirling-image:latest
docker run -d -p 1349:1349 -v stirling-data:/data stirlingimage/stirling-image:latest
```
Includes all tools: image processing, AI-powered background removal, upscaling, face blurring, object erasing, and OCR. Size is ~11 GB due to bundled ML models.
The app is available at `http://localhost:1349`.
## Lite
## GPU acceleration
The image includes CUDA support on amd64. If you have an NVIDIA GPU with the [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html) installed, add `--gpus all`:
```bash
docker pull stirlingimage/stirling-image:lite
docker run -d --gpus all -p 1349:1349 -v stirling-data:/data stirlingimage/stirling-image:latest
```
Includes all image processing tools (resize, crop, rotate, convert, compress, watermark, collage, and 20+ more) but excludes AI/ML tools. Size is ~1-2 GB.
Use this if you:
- Only need standard image processing (no AI features)
- Are running on constrained hardware (Raspberry Pi, small VPS)
- Want faster pulls and smaller disk footprint
### Tools excluded from lite
| Tool | What it does |
|------|-------------|
| Remove Background | AI-powered background removal |
| Upscale | AI super-resolution upscaling |
| Blur Faces | AI face detection and blurring |
| Erase Object | AI inpainting to remove objects |
| OCR | Optical character recognition |
All other tools (27+) work identically in both variants.
## CUDA (GPU acceleration)
```bash
docker pull stirlingimage/stirling-image:cuda
```
Same tools as the full image, but built with GPU-accelerated Python packages (onnxruntime-gpu, PyTorch CUDA, PaddlePaddle GPU). The image auto-detects your NVIDIA GPU at runtime and falls back to CPU if none is found.
Requires [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html) on the host. Linux amd64 only.
The image auto-detects your GPU at runtime. Without `--gpus all`, it runs on CPU. Same image either way.
### Benchmarks
Tested on an NVIDIA RTX 4070 (12 GB VRAM) with a 572x1024 JPEG portrait. Both images ran on the same machine. "Warm" means the model is already loaded in memory (second request onward).
Tested on an NVIDIA RTX 4070 (12 GB VRAM) with a 572x1024 JPEG portrait.
#### Warm performance
@@ -68,10 +43,6 @@ Tested on an NVIDIA RTX 4070 (12 GB VRAM) with a 572x1024 JPEG portrait. Both im
| Upscale 2x | 3,957ms | 2,318ms | 1.7x |
| OCR (PaddleOCR) | 1,469ms | 1,090ms | 1.3x |
Cold start includes loading the model into memory. GPU cold starts are faster because CUDA parallelizes the model loading.
Larger images show bigger speedups, especially for upscaling. Non-AI tools (resize, crop, convert, etc.) are unaffected since they use Sharp (CPU-based).
### GPU health check
After the first AI request, the admin health endpoint reports GPU status:
@@ -83,8 +54,6 @@ GET /api/v1/admin/health
## Docker Compose
### Full
```yaml
services:
stirling-image:
@@ -94,35 +63,24 @@ services:
volumes:
- stirling-data:/data
- stirling-workspace:/tmp/workspace
restart: unless-stopped
logging:
driver: json-file
options:
max-size: "10m"
max-file: "3"
volumes:
stirling-data:
stirling-workspace:
```
### Lite
For GPU acceleration via Docker Compose, add the deploy section:
```yaml
services:
stirling-image:
image: stirlingimage/stirling-image:lite
ports:
- "1349:1349"
volumes:
- stirling-data:/data
- stirling-workspace:/tmp/workspace
volumes:
stirling-data:
stirling-workspace:
```
### CUDA
```yaml
services:
stirling-image:
image: stirlingimage/stirling-image:cuda
image: stirlingimage/stirling-image:latest
ports:
- "1349:1349"
volumes:
@@ -135,35 +93,34 @@ services:
- driver: nvidia
count: 1
capabilities: [gpu]
restart: unless-stopped
volumes:
stirling-data:
stirling-workspace:
```
## Switching from lite to full
To upgrade from lite to full and unlock AI tools:
1. Stop your container
2. Pull the full image: `docker pull stirlingimage/stirling-image:latest`
3. Update your compose file or run command to use `:latest` instead of `:lite`
4. Start the container
Your data and settings are preserved in the volumes.
## Version pinning
Both variants support semver tags for pinning:
| Tag | Description |
|-----|------------|
| `latest` | Latest full release |
| `lite` | Latest lite release |
| `cuda` | Latest full release with GPU support |
| `1.6.0` | Exact full version |
| `1.6.0-lite` | Exact lite version |
| `1.6.0-cuda` | Exact CUDA version |
| `1.6` | Latest patch in 1.6.x (full) |
| `1.6-lite` | Latest patch in 1.6.x (lite) |
| `1.6-cuda` | Latest patch in 1.6.x (CUDA) |
| `latest` | Latest release |
| `1.11.0` | Exact version |
| `1.11` | Latest patch in 1.11.x |
| `1` | Latest minor in 1.x |
## Platforms
| Architecture | GPU support | Notes |
|---|---|---|
| linux/amd64 | NVIDIA CUDA | Full GPU acceleration for AI tools |
| linux/arm64 | CPU only | Raspberry Pi 4/5, Apple Silicon via Docker Desktop |
## Migration from previous tags
If you were using `:lite` or `:cuda` tags, switch to `:latest`:
- **From `:lite`**: Pull `:latest`. You now have all AI tools included.
- **From `:cuda`**: Pull `:latest` and keep `--gpus all`. Same GPU support, unified image.
Your data and settings are preserved in the volumes.