diff --git a/README.md b/README.md
index 4c02966..fb1edf2 100644
--- a/README.md
+++ b/README.md
@@ -111,10 +111,19 @@ For automatic image-based upgrades, Unraid's **Update Container** action pulls t
 
 ## ZimaOS
 
+The simplest path is [`compose.zimaos.yaml`](compose.zimaos.yaml) — a ready-to-import file with the `x-casaos` metadata ZimaOS's app installer and App Store use for the icon, title, and port mapping.
+
+1. In ZimaOS, go to **Docker → Install a Customized App**, and paste or select `compose.zimaos.yaml`.
+2. Before starting it, edit `ADMIN_PASSWORD` and `SESSION_SECRET` in the environment fields.
+3. Confirm the data path — it defaults to `/DATA/AppData/site-gateway` — and start the app.
+4. Open `http://ZIMAOS-IP:8080`.
+
+Prefer a plain Compose file instead? `compose.yaml` (build from source) and `compose.release.yaml` (pull the published image) both work the same way:
+
 1. Copy this folder into ZimaOS storage, e.g. `/DATA/AppData/site-gateway/app`.
 2. Point the Compose volume at `/DATA/AppData/site-gateway/data:/data`.
 3. Set `ADMIN_PASSWORD` and `SESSION_SECRET` (and `PUID`/`PGID` if needed — ZimaOS typically uses `1000:1000`).
-4. Import `compose.yaml` (or `compose.release.yaml` for image-based upgrades) through ZimaOS's custom app / Compose import option, or run it from the terminal:
+4. Import through ZimaOS's custom app / Compose import option, or run it from the terminal:
 
    ```bash
    cd /DATA/AppData/site-gateway/app
diff --git a/compose.release.yaml b/compose.release.yaml
index 9110334..d2c1630 100644
--- a/compose.release.yaml
+++ b/compose.release.yaml
@@ -1,3 +1,8 @@
+
+# Pulls the published multi-arch image instead of building from source.
+# Copy .env.example to .env, set ADMIN_PASSWORD and SESSION_SECRET, then:
+#   docker compose -f compose.release.yaml pull
+#   docker compose -f compose.release.yaml up -d
 services:
   site-gateway:
     image: ${SITE_GATEWAY_IMAGE:-ghcr.io/mfwadejr/site-gateway2:latest}
@@ -18,9 +23,13 @@ services:
     ports:
       - "${HTTP_PORT:-80}:80"
       - "${HTTPS_PORT:-443}:443"
-      - "${HTTPS_PORT:-443}:443/udp"
+      - "${HTTPS_PORT:-443}:443/udp"   # HTTP/3 (QUIC) — forward UDP 443 on your router/firewall too
       - "8080:8080"
       - "9000-9099:9000-9099"
+      # Streaming Hosts (optional): add one line per TCP/UDP port you forward
+      # from the dashboard, matching the target port you'll enter there.
+      # - "25565:25565"
+      # - "25565:25565/udp"
     volumes:
       - ${SITE_GATEWAY_DATA:-/DATA/AppData/site-gateway}:/data
     labels:
diff --git a/compose.yaml b/compose.yaml
index fb89c0b..5b1eab6 100644
--- a/compose.yaml
+++ b/compose.yaml
@@ -1,27 +1,58 @@
+
 services:
   site-gateway:
     build: .
     container_name: site-gateway
     restart: unless-stopped
     environment:
+      # Bootstrap dashboard credentials. Required — change the password before
+      # starting the container. These become the initial Administrator account;
+      # first-time setup will ask you to confirm or replace them.
       ADMIN_USERNAME: admin
       ADMIN_PASSWORD: change-this-password
-      # Optional: set a long random SESSION_SECRET to keep sessions valid across
-      # container rebuilds. If omitted, one is derived from ADMIN_USERNAME/ADMIN_PASSWORD.
+
+      # Optional: set a long random string to keep login sessions valid across
+      # container rebuilds. If omitted, one is derived from the admin
+      # username/password above. Rotating this signs everyone out.
       # SESSION_SECRET: ""
+
+      # Dashboard port inside the container. Change the left side of the
+      # matching entry under `ports:` below if you remap it.
       ADMIN_PORT: 8080
+
+      # Direct-LAN port range Hosted Sites can bind to. Keep this in sync with
+      # the "9000-9099:9000-9099" line under `ports:` below — Docker can't add
+      # a host port to an already-running container, so widen both together
+      # before starting the container if you need a different range.
       SITE_PORT_MIN: 9000
       SITE_PORT_MAX: 9099
+
+      # Where persistent state lives inside the container. Leave this as
+      # /data and change the host side of the volume mount instead.
       DATA_DIR: /data
+
+      # Optional: encryption password for scheduled Complete/Configuration
+      # backups. Leave empty to store backups unencrypted (not recommended,
+      # since Complete backups include certificate private keys).
       BACKUP_PASSWORD: ""
+
+      # User/group the container writes persistent files as. Defaults suit a
+      # typical Linux host; Unraid commonly uses PUID=99, PGID=100.
       PUID: 1000
       PGID: 1000
+
+      # Optional: certificate account email, passed to Caddy's ACME client.
       ACME_EMAIL: ""
     ports:
       - "80:80"
       - "443:443"
-      - "443:443/udp"
+      - "443:443/udp"       # HTTP/3 (QUIC) — forward UDP 443 on your router/firewall too
       - "8080:8080"
       - "9000-9099:9000-9099"
+      # Streaming Hosts (optional): add one line per TCP/UDP port you forward
+      # from the dashboard, matching the target port you'll enter there.
+      # Example for a Minecraft server:
+      # - "25565:25565"
+      # - "25565:25565/udp"
     volumes:
       - ./data:/data
diff --git a/compose.zimaos.yaml b/compose.zimaos.yaml
new file mode 100644
index 0000000..caaa45c
--- /dev/null
+++ b/compose.zimaos.yaml
@@ -0,0 +1,83 @@
+
+# ZimaOS App Store / custom-install compose file for Site Gateway.
+#
+# Import this file directly (ZimaOS → Docker → Install a Customized App →
+# paste/select this file), or use it as the source compose for a ZimaOS
+# App Store submission — the `x-casaos` block below follows ZimaOS's v2
+# app-store schema (see docs.zimaspace.com/docs/developer/app-store-compose-x-casaos).
+#
+# After install, open the ZimaOS app's settings and change ADMIN_PASSWORD
+# and SESSION_SECRET before exposing this to anything beyond your LAN.
+
+name: site-gateway
+
+services:
+  site-gateway:
+    image: ghcr.io/mfwadejr/site-gateway2:latest
+    container_name: site-gateway
+    restart: unless-stopped
+    environment:
+      ADMIN_USERNAME: admin
+      ADMIN_PASSWORD: change-this-password
+      SESSION_SECRET: change-this-too-at-least-32-characters
+      ADMIN_PORT: 8080
+      SITE_PORT_MIN: 9000
+      SITE_PORT_MAX: 9099
+      DATA_DIR: /data
+      BACKUP_PASSWORD: ""
+      # ZimaOS commonly runs its data volumes as 1000:1000; adjust if your
+      # instance differs.
+      PUID: 1000
+      PGID: 1000
+      ACME_EMAIL: ""
+    ports:
+      - target: 8080
+        published: "8080"
+        protocol: tcp
+      - target: 80
+        published: "80"
+        protocol: tcp
+      - target: 443
+        published: "443"
+        protocol: tcp
+      - target: 443
+        published: "443"
+        protocol: udp
+      - target: 9000
+        published: "9000-9099"
+        protocol: tcp
+      # Streaming Hosts (optional): add one entry per TCP/UDP port you forward
+      # from the dashboard, matching the target port you'll enter there.
+      # - target: 25565
+      #   published: "25565"
+      #   protocol: tcp
+    volumes:
+      - type: bind
+        source: /DATA/AppData/site-gateway
+        target: /data
+
+x-casaos:
+  id: dev.mfwadejr.sitegateway
+  main: site-gateway
+  index: /
+  port_map: "8080"
+  scheme: http
+  icon: https://raw.githubusercontent.com/mfwadejr/site-gateway2/main/src/public/site-gateway-icon-approved.png
+  title:
+    en_US: Site Gateway
+  tagline:
+    en_US: Host. Proxy. Secure. A calm dashboard for sites, proxies, and TLS.
+  description:
+    en_US: >-
+      A friendly, self-hosted gateway for homelabs and small teams. Publish
+      static sites, reverse-proxy your apps, forward raw TCP/UDP streams, and
+      manage TLS and access from one dashboard — powered by Caddy.
+  category: Networking
+  author: mfwadejr
+  developer: mfwadejr
+  architectures: ["amd64", "arm64"]
+  version: "0.11.101"
+  update_at: "2026-09-16"
+  website: https://github.com/mfwadejr/site-gateway2
+  repo: https://github.com/mfwadejr/site-gateway2
+  support: https://github.com/mfwadejr/site-gateway2/issues