Self-Hosting gonic with Docker Compose

What Is gonic?

gonic is a lightweight, Subsonic-compatible music streaming server written in Go. It serves your personal music library to any Subsonic API client — DSub, Substreamer, play:Sub, Symfonium, and dozens more. Unlike heavier alternatives, gonic uses an embedded SQLite database, ships as a single binary with no runtime dependencies, and runs comfortably on a Raspberry Pi. It replaces Spotify and Apple Music for streaming your own collection from anywhere.

gonic on GitHub

Prerequisites

A Linux server (Ubuntu 22.04+ recommended)
Docker and Docker Compose installed (guide)
512 MB of free RAM (gonic idles at ~30-80 MB)
A music library on disk (MP3, FLAC, OPUS, APE, M4A, WAV supported)
A domain name (optional, for remote access)

Docker Compose Configuration

Create a docker-compose.yml file:

services:
  gonic:
    image: sentriz/gonic:v0.20.1
    container_name: gonic
    restart: unless-stopped
    environment:
      - TZ=America/New_York
      # Scan music library every 60 minutes
      - GONIC_SCAN_INTERVAL=60
      # Run a full scan on container startup
      - GONIC_SCAN_AT_START_ENABLED=true
      # Watch for file changes in real time via inotify
      - GONIC_SCAN_WATCHER_ENABLED=true
      # Uncomment to handle multi-valued genre tags (e.g., "Rock;Blues")
      # - GONIC_MULTI_VALUE_GENRE=delim ;
      # - GONIC_MULTI_VALUE_ARTIST=delim ;
      # Limit transcode cache to 512 MB
      # - GONIC_TRANSCODE_CACHE_SIZE=512
    ports:
      - "4747:80"
    volumes:
      # Database and user data (persistent)
      - gonic-data:/data
      # Your music library (read-only for safety)
      - /path/to/your/music:/music:ro
      # Transcode and cover art cache
      - gonic-cache:/cache
      # Podcast downloads
      - gonic-podcasts:/podcasts
      # M3U playlist files
      - gonic-playlists:/playlists

volumes:
  gonic-data:
  gonic-cache:
  gonic-podcasts:
  gonic-playlists:

Replace /path/to/your/music with the actual path to your music library on the host.

Start the stack:

docker compose up -d

Initial Setup

Open http://your-server-ip:4747 in your browser
Log in with the default credentials: admin / admin
Change the admin password immediately — there is no environment variable to set it, so this must be done through the web UI
Click Start Scan to index your music library (a 10,000-track library takes roughly 10 minutes)
Install a Subsonic client on your phone or desktop:
- Android: Symfonium, DSub, Substreamer
- iOS: play:Sub, iSub, Amperfy
- Desktop: Supersonic, Submariner (macOS), Sublime Music (Linux)
Point the client at http://your-server-ip:4747 with your gonic username and password

Configuration

gonic uses environment variables exclusively — there is no config file. All settings follow the GONIC_* naming pattern.

Music Library Structure

gonic supports both folder-based and tag-based browsing. For best results, organize your library with one album per directory:

/music/
  Artist Name/
    Album Name (Year)/
      01 - Track.flac
      02 - Track.flac
      cover.jpg

All files in a single folder are treated as belonging to the same album. Mixing tracks from different albums in one directory causes incorrect grouping.

Multiple Music Directories

gonic supports multiple music folders with aliases. Set the environment variable with name->path pairs separated by your system’s path separator:

- GONIC_MUSIC_PATH=rock->/music/rock:jazz->/music/jazz:classical->/music/classical

Multi-Valued Tags

If your library uses delimiters in genre or artist fields (e.g., “Rock;Blues;Folk”), configure gonic to split them:

- GONIC_MULTI_VALUE_GENRE=delim ;
- GONIC_MULTI_VALUE_ARTIST=delim ;
- GONIC_MULTI_VALUE_ALBUM_ARTIST=delim ;

Without this, “Rock;Blues;Folk” is treated as a single genre.

Scrobbling

gonic has built-in Last.fm and ListenBrainz scrobbling. Configure per-user through the web admin UI — each user links their own account. Behind a reverse proxy, set the X-Forwarded-Host header so the Last.fm OAuth callback URL resolves correctly.

Advanced Configuration (Optional)

Jukebox Mode (Server-Side Playback)

gonic can play music through the server’s own audio hardware using MPV. Add these lines to your Docker Compose:

services:
  gonic:
    # ... existing config ...
    group_add:
      - audio
    devices:
      - /dev/snd:/dev/snd
    environment:
      - GONIC_JUKEBOX_ENABLED=true
      # Optional: pipe audio to Snapcast for multi-room
      # - GONIC_JUKEBOX_MPV_EXTRA_ARGS=--ao=pcm --ao-pcm-file=/tmp/snapfifo

Transcoding Profiles

gonic includes 11 built-in transcoding profiles powered by ffmpeg (bundled in the Docker image). Available profiles include MP3 at 128/192/320 kbps, Opus at 96/128/192 kbps, and ReplayGain-normalized variants. Clients request transcoding through the Subsonic API — no server-side configuration needed beyond keeping the defaults.

Podcast Support

gonic can subscribe to and download podcasts. Configure a purge age to automatically clean old episodes:

- GONIC_PODCAST_PURGE_AGE=30

Subscribe to podcast feeds through the web UI or any Subsonic client that supports the podcast API.

Reverse Proxy

Example Nginx configuration for gonic behind a reverse proxy:

server {
    listen 443 ssl;
    server_name music.yourdomain.com;

    location / {
        proxy_pass http://127.0.0.1:4747;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Host $host;
    }
}

The X-Forwarded-Host header is required for Last.fm scrobbling to work correctly behind a reverse proxy.

For full reverse proxy setup instructions, see Reverse Proxy Setup.

Backup

Back up the /data volume — it contains the SQLite database (gonic.db) with all user accounts, playlists, scrobble history, and settings. The music library itself should be backed up separately as part of your broader storage backup strategy.

The /cache volume stores transcoded audio and cover art. It can be safely deleted and will be regenerated on demand, but preserving it saves CPU time.

See Backup Strategy for a comprehensive approach.

Troubleshooting

Music Not Appearing After Adding Files

Symptom: New files added to the music directory don’t show up in clients. Fix: The filesystem watcher (GONIC_SCAN_WATCHER_ENABLED) does not reliably detect deletions on all platforms. Trigger a manual scan from the web UI, or wait for the next scheduled scan interval. Set GONIC_SCAN_INTERVAL=60 as a backup.

Subsonic Client Shows “Authentication Failed”

Symptom: Client can’t connect despite correct credentials. Fix: Some clients send passwords in plaintext while others use token-based auth. Ensure you’re using the username and password set in the gonic web UI. The default credentials are admin/admin — change them after first login.

Last.fm Scrobbling Not Working Behind Reverse Proxy

Symptom: Last.fm OAuth callback fails or redirects to the wrong URL. Fix: Add proxy_set_header X-Forwarded-Host $host; to your Nginx config. Without this header, gonic generates an incorrect callback URL for Last.fm.

Cover Art Not Loading

Symptom: Albums display without cover art in clients. Fix: gonic looks for cover.jpg, cover.png, folder.jpg, or folder.png in album directories, and also extracts embedded cover art from audio files. Ensure GONIC_SCAN_EMBEDDED_COVER_ENABLED is not explicitly set to false. Re-scan after adding cover art files.

High CPU During Playback

Symptom: CPU spikes when streaming music. Fix: This happens during on-the-fly transcoding. If your client is requesting transcoded streams (e.g., MP3 128k from FLAC source), each active stream runs an ffmpeg process. Either play direct (FLAC/original) or limit concurrent transcoding streams. Consider setting GONIC_TRANSCODE_CACHE_SIZE=512 to cache transcoded tracks.

Resource Requirements

RAM: ~30-80 MB idle, ~150-300 MB during library scans (scales with library size)
CPU: Minimal at idle. Transcoding uses one ffmpeg process per active stream
Disk: Application + database under 50 MB. Transcode cache configurable. Music library is the primary storage consumer

gonic is one of the lightest Subsonic servers available — it runs well on a Raspberry Pi or any small SBC.

Verdict

gonic is the best choice if you want a minimal, reliable music server that stays out of your way. It does one thing — serve music via the Subsonic API — and does it with almost zero resource overhead. The embedded SQLite database means no external dependencies, and the Go binary starts in under a second.

Choose gonic over Navidrome if you prefer a server that’s configuration-over-UI and want the absolute lightest resource footprint. Choose Navidrome if you want a polished built-in web player and richer browsing experience. For a federated social music platform, look at Funkwhale instead.

Frequently Asked Questions

Can gonic replace Spotify?

For your own music library — yes. gonic streams your personal music collection to Subsonic-compatible apps on any device. What you lose: Spotify’s catalog of 100M+ songs, discovery algorithms, collaborative playlists, and podcast ecosystem. If you own your music and want to stream it from anywhere, gonic is excellent. It doesn’t help if you rely on Spotify for discovering new music.

Which Subsonic client should I use?

Android: Symfonium (paid, best quality) or DSub (free, reliable). iOS: play:Sub or Amperfy. Desktop: Supersonic (cross-platform), Submariner (macOS). All Subsonic API clients work with gonic — pick whichever interface you prefer.

Can gonic handle FLAC files without transcoding?

Yes. gonic serves original files by default — if your client requests direct playback of FLAC, the server sends the FLAC file with zero CPU overhead. Transcoding only happens when a client requests a different format or bitrate (e.g., MP3 128k for mobile data saving). You control this in your client settings.

How does gonic compare to Navidrome?

Gonic is lighter (~30-80 MB RAM vs Navidrome’s ~100-200 MB), uses configuration-over-UI, and has no built-in web player. Navidrome has a polished web UI with album art browsing, smart playlists, and a Spotify-like experience. Both use the Subsonic API and work with the same mobile clients. Choose gonic for minimalism; choose Navidrome for a richer browsing experience.

Yes. gonic supports multiple user accounts, each with their own Last.fm/ListenBrainz scrobbling connections and playback history. All users access the same music library. Create accounts through the web admin UI.

Does gonic support podcasts?

Yes. gonic can subscribe to podcast feeds, download episodes, and serve them through the Subsonic podcast API. Configure GONIC_PODCAST_PURGE_AGE to auto-clean old episodes. Not all Subsonic clients support the podcast API — check your client’s features.