HEXSONIC

Self-hosted multi-user music platform for modern creators, with strong support for AI music workflows.

HEXSONIC focuses on:

• upload and catalog management
• album/track metadata workflows
• private/public visibility control
• streaming + transcoding
• social features (ratings, comments, follows)
• role-based administration
• OpenSubsonic-compatible API endpoints

Feature Breakdown

Multi-User and Access Control

• OIDC-based login (Keycloak)
• Hierarchical roles: user, member, moderator, admin
• Creator badge gate for upload rights
• Owner-based management boundaries (owner + admin override)
• Persistent login with refresh-token flow

Registration and Invite Flow

• Global registration toggle (admin-controlled)
• Invite-link based onboarding (works even if public registration is disabled)
• Invite lifecycle management (create/list/revoke/expiry)
• Dedicated invite registration entry flow (/register?invite=...)

Library and Visibility Model

• Album and track management separated
• Public/private visibility per album and per track
• Hierarchical behavior for album visibility (album-level public propagation)
• Metadata edit support (title, artist, album, genre, covers, lyrics)

Social and Community Features

• Album comments
• Track rating (stars)
• Public user profiles with follow support
• Uploader attribution in library views

Discovery and Recommendations

• Dedicated Discovery landing page
• Global discovery modules (Top Songs, Trending, Top Albums)
• Personal discovery for logged-in users (For You)
• Recommendation scoring based on listening behavior, ratings, playlist adds, and skips
• Discovery-oriented playback source tracking
• Jukebox beta mode with adaptive rolling queue, live feedback controls, and personal radio-style playback

Creator Analytics

• Dedicated Creator Stats view in the WebUI
• Plays, unique listeners, qualified listens, completed listens, playlist adds, and rating metrics
• Top tracks and top albums by creator
• Traffic-source visibility for creator uploads
• Time-window based analytics (24h, 7d, 30d, 90d, all)

Playback and Client Compatibility

• Web player + advanced popout player
• Playlist queue handling with direct track jump
• Background transcoding pipeline (derived formats for broader client support)
• OpenSubsonic-compatible API for external clients

Admin and Operations

• User administration (roles, moderation, account actions)
• Registration control and invite administration
• Admin log/debug views in WebUI
• Prometheus and Grafana integration (proxied through HEXSONIC)
• Docker-first deployment with systemd autostart support

Intended Use and Legal Notice

HEXSONIC is designed for hosting:

• AI-generated music
• original content you created
• content you are explicitly licensed to distribute

HEXSONIC is not intended for distributing copyrighted material without rights.

The operator of the deployed instance is solely responsible for:

• uploaded content
• copyright compliance
• applicable legal and regulatory obligations

Project contributors provide software only and do not assume liability for operator misuse.

Why HEXSONIC

• Multi-user by design (user/member/mod/admin model)
• Creator-oriented upload and management flows
• Album + track ownership logic
• Built-in discovery landing page with personal + global recommendation layers
• Beta Jukebox engine for personalized radio-style playback
• Creator-facing analytics for uploaded content
• OIDC authentication (Keycloak)
• Admin observability (Grafana + Prometheus via app routes)
• One-command setup with randomized secrets

Quick Start (Recommended)

Run the all-in-one installer:

./setup.sh

setup.sh will:

1. check/install required dependencies (Debian/Ubuntu)
2. generate random passwords/secrets
3. write .env
4. render Keycloak realm import with your generated values
5. build and start Docker services
6. print URLs and initial credentials

After completion, you get:

• Web UI URL
• Keycloak URL
• HEXSONIC admin login
• Keycloak bootstrap admin login

Credentials are also written to:

• runtime/setup/initial-credentials.txt

Architecture (Docker Stack)

• api (Go HTTP API + integrated Web UI)
• worker (transcoding/background jobs)
• postgres (catalog + jobs + app data)
• valkey (cache/queues)
• keycloak (OIDC)
• prometheus (metrics)
• grafana (dashboards)
• oauth2-proxy (Prometheus auth bridge)

Ports

Defaults (change in .env):

• HEXSONIC_PUBLIC_PORT=18080
• KEYCLOAK_PUBLIC_PORT=18081

Grafana and Prometheus are exposed through HEXSONIC routes:

• /grafana/
• /prometheus/

Project Structure

• cmd/hexsonic-api API server entrypoint
• cmd/hexsonic-worker worker entrypoint
• internal/ core backend modules
• web/ Web UI assets
• deploy/ docker/systemd/provisioning assets
• scripts/ operational helpers
• setup.sh one-shot install/bootstrap

Basic Operations

Start/refresh stack:

docker compose up -d --build

Stop stack:

docker compose down

View logs:

docker compose logs -f api worker

systemd Autostart

Install compose autostart service:

sudo bash scripts/install_systemd.sh compose /opt/hexsonic

Service:

• hexsonic-compose.service

OpenSubsonic Compatibility

HEXSONIC exposes OpenSubsonic-style endpoints (e.g. /rest/...) for client compatibility.

Notes:

• Some clients require legacy auth mode
• Some clients require explicit user/password login (not token-only)
• Compatibility coverage is broad but client behavior can vary

Configuration

Use .env.example as reference for all supported variables.

Important:

• never commit real .env values
• never commit generated runtime artifacts
• rotate credentials when moving environments

Security Checklist (Before Internet Exposure)

1. Put HEXSONIC behind a TLS reverse proxy (recommended: DomNexDomain for simpler secure edge handling)
2. Restrict server firewall to required ports
3. Keep host + container images updated
4. Back up Postgres and runtime storage regularly
5. Keep registration settings and role grants under control
6. Audit admin logs and auth events periodically

Development

Build:

make build

Test:

make test

Lint:

make lint

Smoke test:

./scripts/smoke_test.sh

Authenticated smoke test:

AUTH_TOKEN="<ACCESS_TOKEN>" ./scripts/smoke_test.sh

Community Standards

• Code of Conduct
• Contributing Guide
• Security Policy
• Support

Maintainer

• AsaTyr2018 (hauke.lenz@lenz-service.de)

License

Licensed under the Mozilla Public License 2.0 (MPL-2.0).
See LICENSE.

Screenshots