From c282a72bd35db062cec25770a42cf9c803388e44 Mon Sep 17 00:00:00 2001
From: Luca <102960244+Luca-Timo@users.noreply.github.com>
Date: Wed, 29 Apr 2026 15:22:05 +0200
Subject: [PATCH] feat: support Apple Silicon natively via multi-arch images

---
 README.md                       |  2 ++
 docker-compose.mac.override.yml | 27 +++++++++++++++++++++++++++
 2 files changed, 29 insertions(+)
 create mode 100644 docker-compose.mac.override.yml

diff --git a/README.md b/README.md
index d8645fde..23a9cbbd 100644
--- a/README.md
+++ b/README.md
@@ -97,6 +97,8 @@ 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.
+
 ## 🔄 Release Channels
 
 PicPeak offers two release channels for different needs:
diff --git a/docker-compose.mac.override.yml b/docker-compose.mac.override.yml
new file mode 100644
index 00000000..0da0013b
--- /dev/null
+++ b/docker-compose.mac.override.yml
@@ -0,0 +1,27 @@
+# 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