⚙️ Configuration

Advanced configuration and customization options for nJukebox

Configuration Files

nJukebox uses several configuration files to customize behavior and settings:

nJukebox/ ├── config.json # Server configuration (host and ports) ├── njukebox # Compiled Go binary (njukebox.exe on Windows) ├── cmd/njukebox/ # Go entry point ├── internal/ # Go server implementation ├── web/ # Everything the browser loads │ ├── jukebox.html style.css jukebox.js │ └── js/ assets/ locales/ ├── music/ # Local music library └── data/ ├── app.db # Queue, session, settings, Spotify tokens └── music.db # Music library database

Main Configuration (config.json)

The configuration file only covers the server addresses. A missing config.json is fine — the defaults below apply:

{
  "server": {
    "host": "127.0.0.1",
    "webPort": 5500,
    "dataPort": 3001
  }
}

Configuration Options

Server Settings

Setting Default Description
host 127.0.0.1 Bind address (use 0.0.0.0 for network access)
webPort 5500 Web server port (the interface you open in the browser)
dataPort 3001 Data server port (REST API used by the frontend)

Runtime Settings (Admin Panel)

Everything else is configured at runtime in the Admin Panel and stored in the settings database (data/app.db):

  • Admin PIN (default: 1234)
  • Language (German / English)
  • Auto-DJ and track lock time
  • Visualization effects and theming
  • Spotify Client ID and login

Command-Line Flags

One binary serves both ports; flags select what runs:

./njukebox                 # web server on :5500 and data server on :3001
./njukebox --data-only     # only the data server
./njukebox --web-only      # only the web server
./njukebox --root <path>   # use another project directory

Network Configuration

Local Network Access

To allow access from other devices on your network:

  1. Set host to 0.0.0.0 in config.json
  2. Configure your firewall to allow ports 5500 and 3001
  3. Access using your computer's IP address: http://192.168.1.100:5500
Note: Spotify login only works via http://127.0.0.1:5500 — Spotify accepts unencrypted HTTP redirect URIs only for the loopback address.

Port Configuration

If port 5500 or 3001 is in use, change it in multiple places:

  • config.json: Update the webPort or dataPort setting
  • Spotify redirect URI: Update in Spotify Developer Dashboard
  • Batch files: Update any startup scripts

Reverse Proxy Setup

For production deployment behind nginx:

server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://127.0.0.1:5500;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        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_cache_bypass $http_upgrade;
    }
}

Database Configuration

SQLite Settings

nJukebox uses SQLite databases for data storage:

  • app.db: Application settings, user sessions, event data
  • music.db: Music library metadata, play counts, ratings

Database Backup

Regular backups are recommended:

# Windows
copy "data\*.db" "backup\%date%\"

# Linux/macOS
cp data/*.db backup/$(date +%Y%m%d)/

Database Migration

When moving between systems:

  1. Copy the entire data/ directory
  2. Start the binary with --root <path> if the project lives elsewhere
  3. Run a library rescan to update paths

Performance Tuning

Memory Usage

Optimize for different system sizes:

System Size Library Size Recommended Settings
Small (Raspberry Pi) < 1,000 tracks Disable auto-scan, lower scan interval
Medium (Home PC) 1,000 - 10,000 tracks Default settings work well
Large (Server) > 10,000 tracks Enable caching, optimize database

Disk Usage

  • Cover Cache: Can grow large; enable periodic cleanup
  • Log Files: Rotate or delete old log files
  • Temporary Files: Clear cache directory periodically

Security Configuration

Admin PIN Security

Important: Always change the default PIN (1234) in production!
  • Use a strong 4-6 digit PIN
  • Avoid sequential numbers (1234, 2345)
  • Don't use dates or personal information
  • Consider rotating PINs periodically

Network Security

  • Local Only: Keep host as localhost for private use
  • Firewall: Restrict port access to trusted networks
  • HTTPS: Use reverse proxy with SSL for external access
  • VPN: Consider VPN access for remote administration

Internationalization

Adding New Languages

To add a new language:

  1. Copy locales/en.json to locales/[language].json
  2. Translate all text strings
  3. Update the language selector in the admin panel
  4. Test all interface elements

Translation File Structure

{
  "app": {
    "title": "nJukebox",
    "subtitle": "Your Digital Music Experience"
  },
  "navigation": {
    "library": "Library",
    "playlist": "Playlist",
    "search": "Search"
  },
  "admin": {
    "login": "Admin Login",
    "settings": "Settings",
    "reports": "Reports"
  }
}

Advanced Customization

Custom CSS

Override default styles by creating custom.css:

/* Custom color scheme */
:root {
    --primary-color: #ff6b35;
    --background-dark: #1a1a2e;
    --text-primary: #ffffff;
}

/* Custom font */
body {
    font-family: 'Your Custom Font', sans-serif;
}

/* Hide admin button for kiosk mode */
.admin-lock {
    display: none !important;
}

Custom Visualization Effects

Add custom visualizations by extending the effects system:

// Custom effect in js/visualizations/custom.js
class CustomEffect {
    constructor(canvas, audioData) {
        this.canvas = canvas;
        this.ctx = canvas.getContext('2d');
        this.audioData = audioData;
    }
    
    render() {
        // Your custom visualization code
    }
}

Custom API Endpoints

Extend the API by adding custom routes to the Go server (internal/api/), then rebuild the binary:

// In internal/api/
mux.HandleFunc("/api/custom/stats", func(w http.ResponseWriter, r *http.Request) {
    // Custom statistics endpoint
    json.NewEncoder(w).Encode(map[string]any{
        "totalPlays": totalPlays,
        "topGenres":  topGenres,
    })
})
Customization Tip: Keep custom modifications in separate files when possible to make updating easier while preserving your customizations.

Deployment Configurations

Development

Same server, but a normal resizable browser window with DevTools already open and a separate browser profile:

dev.cmd

Kiosk Mode

Start opens the interface in a kiosk browser; stop ends the server and that browser window:

# Windows
start_jukebox.cmd
stop_jukebox.cmd

# Linux/macOS
./start_jukebox.sh
./stop_jukebox.sh

Network Access

{
  "server": {
    "host": "0.0.0.0",
    "webPort": 5500,
    "dataPort": 3001
  }
}
Configuration Management: A missing config.json simply falls back to the defaults — only ship one when you deviate from them.