Docker Operations Guide
Relevant source files
The following files were used as context for generating this wiki page:
The HX-Music Docker environment provides a containerized solution for deploying the C++ server and its associated Python-based lyric processing tools. This setup is specifically targeted at NAS users and developers who require a consistent environment for Japanese song identification and ASS subtitle generation. The Docker deployment encapsulates complex dependencies including Aegisub, Aegisub-cli, and specific Lua automation scripts.
Sources: HX-Music-Server/REAMDE.md:12-13, pyTool/README.md:66-68
Container Architecture
The deployment relies on a single service, hx-music-server, which manages music files, databases, and lyric processing. It integrates the C++ backend with Python tools for karaoke transformation.
The diagram shows the relationship between host volumes, network ports, and internal container components.
Sources: HX-Music-Server/REAMDE.md:16-43, HX-Music-Server/doc/api.md:14-38
Configuration and Deployment
Deployment uses docker-compose to manage the container lifecycle and environment variables.
Environment Variables and Security
The container requires specific capabilities and security options to manage system resources and Aegisub automation.
| Variable/Option | Description | Default/Value |
|---|---|---|
AEGISUB_HOME | Path to Aegisub automation files | /usr/share/aegisub |
seccomp:unconfined | Security profile for system calls | unconfined |
cap_add | Linux capabilities for resource management | SYS_ADMIN, SYS_RESOURCE, NET_ADMIN |
Sources: HX-Music-Server/REAMDE.md:31-43, README.md:65-76
Volume Mapping
The server persists all critical data in a single volume mapping to ensure data survives container updates.
volumes:
- ./data:/loli/HX-Music/data
Sources: HX-Music-Server/REAMDE.md:27-28, README.md:61-62
Data Persistence Structure
The mapped ./data directory follows a specific internal hierarchy for songs, metadata, and databases.
| Host Path | Container Internal Path | Data Description |
|---|---|---|
./data/music/ | /loli/HX-Music/data/music/ | Physical music files (MP3/FLAC/etc.) |
./data/db/ | /loli/HX-Music/data/db/ | SQLite databases (music.db, playlist.db) |
./data/lyrics/ | /loli/HX-Music/data/lyrics/ | Generated .ass lyric files |
./data/musicInfo/ | /loli/HX-Music/data/musicInfo/ | Metadata JSON files per song |
Sources: HX-Music-Server/doc/api.md:17-38
Operational Procedures
Initial Deployment
- Navigate to the
HX-Music-Server/dockerdirectory. - Modify the
docker-compose.yamlif proxy settings are required for downloading dependencies. - Execute the startup command:
docker-compose up -d
Sources: HX-Music-Server/docker/REAMDE.md:7-13
Health Monitoring
The container includes a health check to verify the server is responding to HTTP requests.
Sources: HX-Music-Server/REAMDE.md:33-37
Lyric Processing Workflow
The Docker container automates the complex conversion of raw lyrics to Japanese karaoke subtitles.
- Upload: User pushes a song via the
/music/upload/push/{pushId}endpoint. - Identification: Server identifies the song and fetches lyrics from sources like QQ Music, NetEase, or Lrclib.
- Processing: The internal Python tool performs Japanese furigana injection.
- Template Application:
aegisub-cliapplies the karaoke Lua template to generate the final ASS file.
Sources: HX-Music-Server/doc/api.md:73-83, pyTool/README.md:46-60, README.md:12-15
HX-Music utilizes Docker to simplify the installation of Aegisub-cli and associated C++20 dependencies, providing a plug-and-play experience for private music server deployment.
Sources: pyTool/README.md:52-59, HX-Music-Server/docker/REAMDE.md:1-5