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.

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.

2.1 KiB Raw Blame History