Deploying Gonic

Introduction

Gonic is a lightweight, Subsonic-compatible music streaming server written in Go. It allows you to stream your personal music collection from anywhere using any Subsonic-compatible client app on desktop, mobile, or web.

Unlike heavier alternatives, Gonic is designed for efficiency. It does not perform any audio transcoding by default (though it supports it optionally), does not generate thumbnails, and has minimal resource requirements. This makes it perfect for low-power devices and containerized deployments.

Key highlights of Gonic:

Subsonic API Compatible: Works with all Subsonic and Airsonic clients
Lightweight: Minimal CPU and memory usage
Fast Scanning: Quick music library indexing
Multiple Folders: Support for multiple music directories
Podcast Support: Download and manage podcasts
Internet Radio: Stream internet radio stations
Scrobbling: Last.fm and ListenBrainz integration
Transcoding: Optional on-the-fly audio conversion
Multi-User: Support for multiple user accounts
Jukebox Mode: Control playback on the server
Open Source: Licensed under GPL-3.0

This guide walks through deploying Gonic on Klutch.sh using Docker.

Why Deploy Gonic on Klutch.sh

Deploying Gonic on Klutch.sh provides several advantages:

Stream Anywhere: Access your music library from any location with internet.

Persistent Library: Your music metadata survives container updates.

HTTPS by Default: Secure streaming without certificate management.

Low Resources: Efficient design works well with minimal allocation.

Always On: Your music server runs 24/7 without home network hassles.

Prerequisites

Before deploying Gonic on Klutch.sh, ensure you have:

A Klutch.sh account
A GitHub account with a repository for your configuration
Your music library files (to upload to persistent storage)
A Subsonic-compatible music player app
Basic familiarity with Docker

Understanding Gonic Architecture

Gonic has a simple architecture:

Go HTTP Server: Handles Subsonic API requests and web interface.

SQLite Database: Stores music metadata, users, and playlists.

File Scanner: Indexes music files from configured directories.

Optional FFmpeg: For transcoding when needed.

Preparing Your Repository

Create a GitHub repository with your Gonic configuration.

Repository Structure

gonic-deploy/
├── Dockerfile
└── .dockerignore

Creating the Dockerfile

FROM sentriz/gonic:latest

# Set environment variables
ENV GONIC_MUSIC_PATH=/music
ENV GONIC_PODCAST_PATH=/podcasts
ENV GONIC_CACHE_PATH=/cache
ENV GONIC_DB_PATH=/data/gonic.db
ENV GONIC_LISTEN_ADDR=0.0.0.0:4747

# Create directories
RUN mkdir -p /music /podcasts /cache /data

# Expose web interface
EXPOSE 4747

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:4747/ping || exit 1

Advanced Dockerfile with Transcoding

For transcoding support:

FROM sentriz/gonic:latest

# Install FFmpeg for transcoding
USER root
RUN apk add --no-cache ffmpeg
USER gonic

# Set environment variables
ENV GONIC_MUSIC_PATH=/music
ENV GONIC_PODCAST_PATH=/podcasts
ENV GONIC_CACHE_PATH=/cache
ENV GONIC_DB_PATH=/data/gonic.db
ENV GONIC_LISTEN_ADDR=0.0.0.0:4747

# Create directories
RUN mkdir -p /music /podcasts /cache /data

EXPOSE 4747

HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:4747/ping || exit 1

Environment Variables Reference

Variable	Required	Description
`GONIC_MUSIC_PATH`	Yes	Path to music library
`GONIC_PODCAST_PATH`	No	Path for podcast downloads
`GONIC_CACHE_PATH`	No	Path for cache files
`GONIC_DB_PATH`	Yes	Path to SQLite database
`GONIC_LISTEN_ADDR`	No	Listen address (default: :4747)
`GONIC_SCAN_INTERVAL`	No	Library scan interval in minutes
`GONIC_JUKEBOX_ENABLED`	No	Enable jukebox mode

Deploying Gonic on Klutch.sh

Push Your Repository to GitHub

Commit your Dockerfile to GitHub.

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project named “gonic” or “music-server”.

Create a New App

Create a new app and connect your GitHub repository.

Configure HTTP Traffic

Set up HTTP traffic:

Select HTTP as the traffic type
Set the internal port to 4747

Set Environment Variables

Variable	Value
`GONIC_MUSIC_PATH`	/music
`GONIC_DB_PATH`	/data/gonic.db
`GONIC_SCAN_INTERVAL`	60

Attach Persistent Volumes

Mount Path	Size	Purpose
`/music`	100+ GB	Music library files
`/data`	1 GB	Database and configuration
`/cache`	10 GB	Transcoding cache
`/podcasts`	10 GB	Podcast downloads

Deploy Your Application

Click Deploy to build and launch Gonic.

Upload Your Music

Transfer your music files to the /music volume.

Complete Initial Setup

Access Gonic at your app URL. Create your admin account to get started.

Initial Configuration

Creating Admin Account

Navigate to your Gonic URL
Create the first (admin) user
Set a strong password
This user has full administrative access

Adding Music Folders

Gonic scans from the configured music path:

Upload music to /music directory
Organize by Artist/Album structure
Trigger a scan from the admin interface

Multiple Music Folders

Support multiple source directories:

GONIC_MUSIC_PATH=/music:/music2:/music3

Client Apps

Mobile Apps

Popular Subsonic clients:

Android:

Ultrasonic
DSub
Substreamer
Tempo

iOS:

play:Sub
Substreamer
Amperfy

Desktop Apps

Sublime Music (Linux/macOS)
Submariner (macOS)
Sonixd (cross-platform)

Web Players

Airsonic Refix
Subplayer
Jamstash

Configuring Clients

Server Settings

In your Subsonic client:

Server URL: https://your-app.klutch.sh
Username: Your Gonic username
Password: Your Gonic password
Enable HTTPS: Yes

Music Library Organization

Recommended Structure

/music/
├── Artist Name/
│   ├── Album Name (Year)/
│   │   ├── 01 - Track Name.mp3
│   │   ├── 02 - Track Name.mp3
│   │   └── cover.jpg
│   └── Another Album/
└── Another Artist/

Supported Formats

Gonic supports common audio formats:

MP3
FLAC
OGG
AAC/M4A
WAV
OPUS

Transcoding

When to Use Transcoding

Transcoding converts audio on-the-fly:

Reduce bandwidth for mobile data
Convert FLAC to smaller formats
Compatibility with older devices

FFmpeg Configuration

Gonic uses FFmpeg for transcoding. Common profiles:

Format	Bitrate	Use Case
MP3	320k	High quality
MP3	192k	Good quality, less data
MP3	128k	Mobile data saving
Opus	128k	Efficient modern codec

Podcast Support

Adding Podcasts

Go to Settings > Podcasts
Add podcast RSS feed URL
Gonic downloads episodes automatically

Podcast Settings

Download interval
Episode retention
Storage location

Scrobbling

Last.fm Integration

Go to Settings > Last.fm
Link your Last.fm account
Plays are scrobbled automatically

ListenBrainz Integration

Go to Settings > ListenBrainz
Enter your API token
Plays are submitted automatically

Multi-User Setup

Creating Users

Log in as admin
Go to User Management
Create new users
Set permissions

User Permissions

Admin: Full access
User: Stream and create playlists
Guest: Stream only

Performance Tips

Library Scanning

Initial scan may take time for large libraries
Subsequent scans are incremental
Set scan interval based on library changes

Resource Usage

Disable transcoding if not needed
Use appropriate cache size
Monitor memory during scans

Troubleshooting

Music Not Appearing

Verify files are in correct path
Check file format is supported
Trigger manual scan
Review scan logs

Playback Issues

Check client settings
Verify network connectivity
Test with different client

Transcoding Errors

Verify FFmpeg is installed
Check transcoding profiles
Review error logs

Additional Resources

Conclusion

Deploying Gonic on Klutch.sh provides a lightweight, efficient music streaming solution for your personal library. With Subsonic compatibility, you can use your preferred client app on any device to access your music from anywhere.

The combination of Gonic’s minimal resource usage and Klutch.sh’s reliable hosting creates an ideal platform for personal music streaming.