Feishin Deployment and Usage Guide

1. Prerequisites

Required:

A music server running one of:
- Jellyfin (latest version)
- Navidrome (0.48.0+ recommended for full feature support)
- Subsonic/OpenSubsonic compatible server
Node.js 18+ (for development/building)
npm or yarn package manager

Optional but recommended:

MPV player (for desktop client with MPV backend)
- Download from mpv.io or install via your system package manager
Docker and Docker Compose (for containerized deployment)

2. Installation

Desktop Client (Recommended)

Download the latest desktop client from the GitHub Releases page.

macOS Notes:

For macOS 12 (Monterey) or higher, you may need to remove the app from quarantine. See issue #104 for instructions.
For media key support, allow Feishin as a Trusted Accessibility Client when prompted, then restart the application.

Linux Installation: Use the provided install script for AppImage:

# Install Feishin
dir=/your/application/directory
curl 'https://raw.githubusercontent.com/jeffvli/feishin/refs/heads/development/install-feishin-appimage' | sh -s -- "$dir"

# For experimental Wayland mode (unsupported):
curl 'https://raw.githubusercontent.com/jeffvli/feishin/refs/heads/development/install-feishin-appimage' | sh -s -- "$dir" wayland-native

# Uninstall:
curl 'https://raw.githubusercontent.com/jeffvli/feishin/refs/heads/development/install-feishin-appimage' | sh -s -- "$dir" remove

Docker Deployment

Quick Start:

# Run latest version
docker run --name feishin -p 9180:9180 ghcr.io/jeffvli/feishin:latest

# Build locally
docker build -t feishin .
docker run --name feishin -p 9180:9180 feishin

Web Version

Access the hosted web client at https://feishin.vercel.app (web player backend only).

3. Configuration

Server Connection

On first launch, you'll be prompted to configure your music server:

Select Server Type: Jellyfin, Navidrome, or Subsonic
Enter Server URL: http://your-server:port or https://your-server:port
Provide Credentials: Username and password for your music server

MPV Configuration (Desktop Only)

If using the desktop client with MPV backend, you'll be prompted to:

Provide the path to your MPV binary (automatically detected if installed in standard locations)
Configure MPV settings through the player settings interface

Environment Variables (Docker)

Configure via Docker Compose or environment variables:

# docker-compose.yml example
services:
  feishin:
    container_name: feishin
    image: 'ghcr.io/jeffvli/feishin:latest'
    restart: unless-stopped
    environment:
      - SERVER_NAME=jellyfin              # Pre-defined server name
      - SERVER_LOCK=true                  # Lock server settings when true
      - SERVER_TYPE=jellyfin              # jellyfin, navidrome, or subsonic (case-insensitive)
      - SERVER_URL=http://your-server:8096 # Your music server URL
      - LEGACY_AUTHENTICATION=false       # Plaintext auth for Subsonic/OpenSubsonic
      - ANALYTICS_DISABLED=true          # Disable Umami analytics tracking
    ports:
      - 9180:9180
      # Or restrict to localhost: - 127.0.0.1:9180:9180

Key Configuration Options:

SERVER_LOCK=true: When enabled with server name/type/url set, only username/password can be changed
LEGACY_AUTHENTICATION: Set to true for Subsonic servers requiring plaintext authentication
Port 9180: Default web interface port

4. Build & Run (Development)

Clone and Setup

# Clone the repository
git clone https://github.com/jeffvli/feishin.git
cd feishin

# Install dependencies
npm install
# or
yarn install

Development Mode

# Start development server
npm run dev
# or
yarn dev

The application will start in development mode with hot-reload enabled.

Production Build

# Build for production
npm run build
# or
yarn build

# Build for specific platform
npm run build:win
npm run build:mac
npm run build:linux

Electron Development

# Start Electron in development mode
npm run electron:dev

# Package Electron app
npm run electron:build

5. Deployment

Docker Deployment (Recommended for Self-Hosting)

Docker Compose (Production):

version: '3.8'
services:
  feishin:
    image: ghcr.io/jeffvli/feishin:latest
    container_name: feishin
    restart: unless-stopped
    ports:
      - "9180:9180"
    environment:
      - SERVER_TYPE=navidrome
      - SERVER_URL=https://music.yourdomain.com
      - SERVER_LOCK=true
      - ANALYTICS_DISABLED=true
    # Optional volumes for persistence:
    # volumes:
    #   - ./feishin-data:/app/data

Update Strategy:

# Pull latest image and restart
docker-compose pull feishin
docker-compose up -d feishin

Platform-Specific Deployment Options

Traditional Server:
- Build the web version and serve via nginx/Apache
- Configure reverse proxy with SSL termination
Cloud Platforms:
- Vercel: Deploy web version directly (limited to web player)
- Railway/Render: Deploy Docker container with persistent storage
- Fly.io: Deploy with global CDN for better performance
Desktop Distribution:
- Package platform-specific installers using Electron Builder
- Distribute through package managers (Homebrew, Snap, AUR)

Reverse Proxy Configuration (Nginx Example)

server {
    listen 80;
    server_name feishin.yourdomain.com;
    
    location / {
        proxy_pass http://localhost:9180;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
    
    # Add SSL configuration for HTTPS
}

6. Troubleshooting

Common Issues

1. MPV Not Found (Desktop Client)

Error: MPV binary not found

Solution: Install MPV from mpv.io or via package manager:

Ubuntu/Debian: sudo apt install mpv
macOS: brew install mpv
Windows: Download installer from mpv.io

2. Server Connection Failed

Cannot connect to music server

Solutions:

Verify server URL and port are correct
Check if server is running and accessible
For Jellyfin: Ensure "Allow remote connections" is enabled
For Navidrome: Verify ND_ENABLEPLAYLISTS=true is set if using smart playlists

3. Media Keys Not Working (macOS) Solution:

Go to System Settings > Privacy & Security > Accessibility
Add Feishin to the allowed apps list
Restart Feishin completely

4. Docker Container Won't Start Solutions:

Check port conflicts: sudo lsof -i :9180
Verify Docker daemon is running: sudo systemctl status docker
Check container logs: docker logs feishin

5. Lyrics Not Loading Solution:

Desktop client: Built-in lyrics fetching requires internet connection
Web client: Lyrics support depends on your music server's capabilities
Verify your music server has lyrics plugins/enabled features

6. Update Issues Solution for alpha channel updates:

# Check current channel
# In settings, verify release channel is set correctly

# Manual update check
# Desktop: Help → Check for Updates
# Docker: Pull latest image and recreate container

Debug Mode

Desktop Client:

Start from terminal: ./Feishin --debug (or equivalent for your OS)
Check logs in:
- Linux: ~/.config/Feishin/logs/main.log
- macOS: ~/Library/Logs/Feishin/main.log
- Windows: %APPDATA%\Feishin\logs\main.log

Docker Container:

# Run with shell access
docker run -it --rm -p 9180:9180 ghcr.io/jeffvli/feishin:latest /bin/sh

# View logs
docker logs -f feishin

Getting Help

Discord: Join Discord server
Matrix: #sonixd:matrix.org
GitHub Issues: Report bugs
Feature Requests: GitHub Project Board

How to Deploy & Use feishin