From d272cb51e13a84e206fe1ad571c4f7db63870102 Mon Sep 17 00:00:00 2001
From: Khoa Vo <vndangkhoa@gmail.com>
Date: Fri, 20 Mar 2026 23:04:36 +0700
Subject: [PATCH] docs: add Synology deployment guide for future agents

---
 SYNOLOGY_DEPLOYMENT_GUIDE.md | 32 ++++++++++++++++++++++++++++++++
 1 file changed, 32 insertions(+)
 create mode 100644 SYNOLOGY_DEPLOYMENT_GUIDE.md

diff --git a/SYNOLOGY_DEPLOYMENT_GUIDE.md b/SYNOLOGY_DEPLOYMENT_GUIDE.md
new file mode 100644
index 0000000..a2998e5
--- /dev/null
+++ b/SYNOLOGY_DEPLOYMENT_GUIDE.md
@@ -0,0 +1,32 @@
+# Synology DS920+ Deployment & Stability Guide
+*Priority Technical Instructions for AI Agents*
+
+This application has been specifically optimized for deployment on a **Synology DS920+ (x86_64)**. To ensure future updates don't break the deployment, follow these mandatory rules:
+
+## 1. Unified OS Environment
+- **Requirement**: Use `debian:bookworm-slim` for both the build stages and the final runtime stage in the `Dockerfile`.
+- **Reason**: Synology's kernel and library system (glibc) are highly compatible with Debian Bookworm. Mismatches between builder images (e.g., node-alpine) and runtime images (e.g., python-slim) will cause silent execution failures on the NAS.
+
+## 2. Axum 0.8 Routing (Critical)
+- **Warning**: Axum 0.8 removed support for "nesting" at the root path (`/`).
+- **Fix**: Never use `.nest_service("/", ...)` for static files. Instead, use `.fallback_service(ServeDir::new("static"))`.
+- **Symptoms**: Incorrect nesting causes an immediate panic on startup, often with no logs in the Docker container manager.
+
+## 3. Immediate Log Flushing
+- **Implementation**: In `main.rs`, always force-flush `stdout` and `stderr` after critical startup messages.
+```rust
+println!("SERVER STARTING UP...");
+std::io::stdout().flush().unwrap();
+```
+- **Reason**: Synology Container Manager's log buffer can "swallow" early panic messages if the process dies instantly. Explicit flushing ensures the error appears in the GUI.
+
+## 4. Docker Compatibility
+- **Compose Version**: Use `version: "3.8"` or lower in `docker-compose.yml`.
+- **API Version**: If running via CLI/SSH, export `DOCKER_API_VERSION=1.43` to match the NAS daemon.
+- **Image Strategy**: If registry pull/push fails with "No logs," always fallback to building directly on the NAS via SSH using:
+  `sudo docker build -t spotify-local:latest .`
+
+## 5. Runtime Dependencies
+- **libssl3 / zlib1g**: Must be explicitly installed in the final Docker stage.
+- **Node.js**: Required in the final stage for `yt-dlp` JS-runtime features.
+- **Python venv**: Use a virtual environment (`/opt/venv`) to avoid "externally managed environment" errors in Debian Bookworm.