From 0e820fe451d28cc71349e7cbbc7d37b0872f209b Mon Sep 17 00:00:00 2001
From: crypt0rr <57799908+crypt0rr@users.noreply.github.com>
Date: Fri, 30 Jan 2026 14:57:58 +0100
Subject: [PATCH 1/2] Add Homebox service with Tailscale sidecar

---
 services/homebox/.env         | 17 +++++++++
 services/homebox/README.md    | 54 +++++++++++++++++++++++++++
 services/homebox/compose.yaml | 70 +++++++++++++++++++++++++++++++++++
 3 files changed, 141 insertions(+)
 create mode 100644 services/homebox/.env
 create mode 100644 services/homebox/README.md
 create mode 100644 services/homebox/compose.yaml

diff --git a/services/homebox/.env b/services/homebox/.env
new file mode 100644
index 0000000..972e64a
--- /dev/null
+++ b/services/homebox/.env
@@ -0,0 +1,17 @@
+#version=1.1
+#URL=https://github.com/tailscale-dev/ScaleTail
+#COMPOSE_PROJECT_NAME= # Optional: only use when running multiple deployments on the same infrastructure.
+
+# Service Configuration
+SERVICE=homebox # Service name (e.g., adguard). Used as hostname in Tailscale and for container naming (app-${SERVICE}).
+IMAGE_URL=ghcr.io/sysadminsmedia/homebox:latest # Docker image URL from container registry (e.g., adguard/adguard-home).
+
+# Network Configuration
+SERVICEPORT=7745 # Port to expose to local network. Uncomment the "ports:" section in compose.yaml to enable.
+DNS_SERVER=9.9.9.9 # Preferred DNS server for Tailscale. Uncomment the "dns:" section in compose.yaml to enable.
+
+# Tailscale Configuration
+TS_AUTHKEY= # Auth key from https://tailscale.com/admin/authkeys. See: https://tailscale.com/kb/1085/auth-keys#generate-an-auth-key for instructions.
+
+# Optional Service variables
+# PUID=1000
diff --git a/services/homebox/README.md b/services/homebox/README.md
new file mode 100644
index 0000000..c5823c2
--- /dev/null
+++ b/services/homebox/README.md
@@ -0,0 +1,54 @@
+# Homebox with Tailscale Sidecar Configuration
+
+This Docker Compose configuration sets up **Homebox** with a Tailscale sidecar container, enabling secure access to your self-hosted inventory and asset management system over your private Tailscale network. With this setup, your Homebox instance remains **private and accessible only from authorized devices on your Tailnet**, keeping inventory data and asset metadata protected from public exposure.
+
+## Homebox
+
+[**Homebox**](https://github.com/sysadminsmedia/homebox) is an open-source, self-hosted home inventory and asset management application developed by SysAdmins Media. It allows you to catalog items, assign them to locations, track quantities, warranties, purchase details, and custom metadata through a clean and intuitive web interface.
+
+Homebox is well suited for homelabs, workshops, offices, and households that want a lightweight but structured way to manage physical assets without relying on third-party SaaS platforms.
+
+## Key Features
+
+- 📦 **Item Inventory** – Track items with names, descriptions, quantities, and images
+- 📍 **Location Management** – Organize assets by rooms, racks, shelves, or custom locations
+- 🏷️ **Custom Fields & Metadata** – Extend items with your own structured data
+- 🧾 **Warranty & Purchase Tracking** – Store purchase dates, vendors, and warranty details
+- 🔍 **Search & Filtering** – Quickly find items across large inventories
+- 👥 **Multi-User Support** – Share access with trusted users
+- 🐳 **Docker-Friendly** – Designed for containerized deployments
+- 📦 **Open Source** – Fully self-hosted with no external dependencies
+
+## Why Self-Host?
+
+Inventory and asset data often reflects **physical security, infrastructure layout, and ownership details**. Self-hosting Homebox ensures full control over this information, eliminates dependency on cloud services, and allows deployment in restricted or offline environments.
+
+When combined with Tailscale, Homebox becomes a **secure, Tailnet-only inventory system** that is reachable from anywhere you need it, without exposing ports or services to the public internet.
+
+## Configuration Overview
+
+In this deployment, a **Tailscale sidecar container** (for example `tailscale-homebox`) runs the Tailscale client and joins your private Tailscale network. The main `homebox` service uses:
+
+```plain
+network_mode: service:tailscale-homebox
+```
+
+This configuration routes all inbound and outbound traffic through the Tailscale interface, ensuring that the Homebox web UI and API are accessible **only via your Tailscale network**. No public port exposure is required unless explicitly configured.
+
+Homebox listens internally on port **7745**, which is the port that should be referenced if Tailscale Serve is enabled.
+
+## Volume Permissions
+
+Homebox stores all persistent data under `/data` inside the container. When using bind mounts, the host directory **must be pre-created with the correct ownership**, otherwise Docker will create it as `root:root`, which will cause permission issues when running the container as a non-root user.
+
+Before starting the stack, ensure the data directory is owned by UID/GID `65532`:
+
+```plain
+chown 65532:65532 homebox-data/
+```
+
+This is especially important when using the rootless or hardened Homebox images and when running the service with:
+
+```plain
+user: 65532:65532
+```
diff --git a/services/homebox/compose.yaml b/services/homebox/compose.yaml
new file mode 100644
index 0000000..f51842a
--- /dev/null
+++ b/services/homebox/compose.yaml
@@ -0,0 +1,70 @@
+configs:
+  ts-serve:
+    content: |
+      {"TCP":{"443":{"HTTPS":true}},
+      "Web":{"$${TS_CERT_DOMAIN}:443":
+          {"Handlers":{"/":
+          {"Proxy":"http://127.0.0.1:7745"}}}},
+      "AllowFunnel":{"$${TS_CERT_DOMAIN}:443":false}}
+
+services:
+# Make sure you have updated/checked the .env file with the correct variables. 
+# All the ${ xx } need to be defined there.
+  # Tailscale Sidecar Configuration
+  tailscale:
+    image: tailscale/tailscale:latest # Image to be used
+    container_name: tailscale-${SERVICE} # Name for local container management
+    hostname: ${SERVICE} # Name used within your Tailscale environment
+    environment:
+      - TS_AUTHKEY=${TS_AUTHKEY}
+      - TS_STATE_DIR=/var/lib/tailscale
+      - TS_SERVE_CONFIG=/config/serve.json # Tailscale Serve configuration to expose the web interface on your local Tailnet - remove this line if not required
+      - TS_USERSPACE=false
+      - TS_ENABLE_HEALTH_CHECK=true              # Enable healthcheck endpoint: "/healthz"
+      - TS_LOCAL_ADDR_PORT=127.0.0.1:41234       # The <addr>:<port> for the healthz endpoint
+      #- TS_ACCEPT_DNS=true # Uncomment when using MagicDNS
+    configs:
+      - source: ts-serve
+        target: /config/serve.json
+    volumes:
+      - ./config:/config # Config folder used to store Tailscale files - you may need to change the path
+      - ./ts/state:/var/lib/tailscale # Tailscale requirement - you may need to change the path
+    devices:
+      - /dev/net/tun:/dev/net/tun # Network configuration for Tailscale to work
+    cap_add:
+      - net_admin # Tailscale requirement
+    #ports:
+    #  - 0.0.0.0:${SERVICEPORT}:${SERVICEPORT} # Binding port ${SERVICE}PORT to the local network - may be removed if only exposure to your Tailnet is required
+    # If any DNS issues arise, use your preferred DNS provider by uncommenting the config below
+    #dns: 
+    #  - ${DNS_SERVER}
+    healthcheck:
+      test: ["CMD", "wget", "--spider", "-q", "http://127.0.0.1:41234/healthz"] # Check Tailscale has a Tailnet IP and is operational
+      interval: 1m # How often to perform the check
+      timeout: 10s # Time to wait for the check to succeed
+      retries: 3 # Number of retries before marking as unhealthy
+      start_period: 10s # Time to wait before starting health checks
+    restart: always
+
+  # ${SERVICE}
+  application:
+    image: ${IMAGE_URL} # Image to be used
+    network_mode: service:tailscale # Sidecar configuration to route ${SERVICE} through Tailscale
+    container_name: app-${SERVICE} # Name for local container management
+    user: "65532:65532"
+    environment:
+      - PUID=1000
+      - PGID=1000
+      - TZ=Europe/Amsterdam
+    volumes:
+      - ./${SERVICE}-data:/data
+    depends_on:
+      tailscale:
+        condition: service_healthy
+    healthcheck:
+      test: ["CMD", "pgrep", "-f", "${SERVICE}"] # Check if ${SERVICE} process is running
+      interval: 1m # How often to perform the check
+      timeout: 10s # Time to wait for the check to succeed
+      retries: 3 # Number of retries before marking as unhealthy
+      start_period: 30s # Time to wait before starting health checks
+    restart: always
\ No newline at end of file

From ae0e31e160f4e18ba74b05abfd9a99f090b2d8f1 Mon Sep 17 00:00:00 2001
From: crypt0rr <57799908+crypt0rr@users.noreply.github.com>
Date: Fri, 30 Jan 2026 15:03:13 +0100
Subject: [PATCH 2/2] Health update

---
 services/homebox/compose.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/services/homebox/compose.yaml b/services/homebox/compose.yaml
index f51842a..acb3e7c 100644
--- a/services/homebox/compose.yaml
+++ b/services/homebox/compose.yaml
@@ -62,7 +62,7 @@ services:
       tailscale:
         condition: service_healthy
     healthcheck:
-      test: ["CMD", "pgrep", "-f", "${SERVICE}"] # Check if ${SERVICE} process is running
+      test: ["CMD", "pgrep", "-f", "api"] # Check if ${SERVICE} process is running
       interval: 1m # How often to perform the check
       timeout: 10s # Time to wait for the check to succeed
       retries: 3 # Number of retries before marking as unhealthy