diff --git a/README.md b/README.md index 23a9cbbd..b1398621 100644 --- a/README.md +++ b/README.md @@ -97,7 +97,7 @@ Note on Docker file permissions (PUID/PGID) - `PGID=1000` - Without this, creating events, uploads, thumbnails, or logs can fail with "Permission denied". -**ARM64 (aarch64) systems:** Pre-built images include native `linux/arm64`, no platform flags or emulation needed. If you're on an older image tag that's still amd64-only, see [docker-compose.mac.override.yml](docker-compose.mac.override.yml) for a transitional fallback. +**ARM64 (aarch64) systems:** Pre-built images include native `linux/arm64`, no platform flags or emulation needed. If you're on an older image tag that's still amd64-only, see [docker-compose.amd64.override.yml](docker-compose.amd64.override.yml) for a transitional fallback. ## 🔄 Release Channels diff --git a/docker-compose.amd64.override.yml b/docker-compose.amd64.override.yml new file mode 100644 index 00000000..bda75227 --- /dev/null +++ b/docker-compose.amd64.override.yml @@ -0,0 +1,33 @@ +# Force linux/amd64 for the PicPeak backend and frontend images. +# +# When you need this: +# You're on an ARM64 host (Apple Silicon Mac, Raspberry Pi, AWS Graviton, +# Ampere, etc.) AND the image tag you're pulling does NOT yet have a +# linux/arm64 variant — for example, an older :latest or a pre-multi-arch +# :stable still cached locally. +# +# When you do NOT need this: +# Once you're on a release whose backend/frontend manifests include both +# linux/amd64 and linux/arm64, Docker selects the native arm64 image +# automatically. Drop this override. +# +# Usage: +# +# docker compose \ +# -f docker-compose.production.yml \ +# -f docker-compose.amd64.override.yml \ +# up -d +# +# Performance note: forcing amd64 on an ARM64 Linux host invokes qemu-user +# emulation, which is significantly slower (especially for the backend's +# Node.js workloads). Apple Silicon uses Rosetta 2, which is faster but still +# slower than native arm64. Prefer pulling a multi-arch tag whenever possible. +# +# postgres + redis are intentionally omitted — their upstream images are +# already multi-arch and pull natively on every supported architecture. + +services: + backend: + platform: linux/amd64 + frontend: + platform: linux/amd64 diff --git a/docker-compose.mac.override.yml b/docker-compose.mac.override.yml deleted file mode 100644 index 0da0013b..00000000 --- a/docker-compose.mac.override.yml +++ /dev/null @@ -1,27 +0,0 @@ -# Apple Silicon (ARM64) fallback override. -# -# This file is ONLY needed for Mac users who are pulling an image tag that was -# published before multi-arch CI was rolled out (e.g. an old :latest or a -# pre-multi-arch :stable still in your local cache). -# -# Once you're on a release whose backend/frontend manifests include linux/arm64, -# you do NOT need this file — Docker selects the native arm64 image automatically. -# -# Usage (Mac Studio / Apple Silicon only): -# -# docker compose \ -# -f docker-compose.production.yml \ -# -f docker-compose.mac.override.yml \ -# up -d -# -# Linux users: do NOT load this file. Forcing platform: linux/amd64 on Linux -# ARM64 hosts (Raspberry Pi, AWS Graviton, etc.) would push you into emulation. -# -# postgres + redis are omitted — their upstream images are already multi-arch -# and run natively on Apple Silicon without any platform flag. - -services: - backend: - platform: linux/amd64 - frontend: - platform: linux/amd64