Skip to content

FAQ

Jump to bottom
Bram Vandeperre edited this page Oct 22, 2025 · 1 revision

Frequently Asked Questions (FAQ)

Table of Contents

Setup & Configuration

How do I access the admin panel?

The admin panel runs on port 3001 by default. Access it at:

  • http://localhost:3001 (local development)
  • http://your-server:3001 (production)

Authentication:

  • If ADMIN_USERNAME and ADMIN_PASSWORD environment variables are set, you'll need to log in
  • Without these variables, the admin panel is accessible without authentication (not recommended for production)

Can I run this without Docker?

Yes, but Docker is recommended. For manual setup:

# Install dependencies
npm install

# Build the frontend and admin panel
npm run build
npm run admin:build

# Start the server
npm start

You'll need Node.js 18 or higher.

How do I change the default ports?

Set environment variables in your docker-compose.yml:

environment:
  - PORT=3000          # Main app port (default: 3000)
  - ADMIN_PORT=3001    # Admin panel port (default: 3001)

Where is data stored?

All data is stored in the ./data directory:

  • config.json - Base URL, branding, NPM settings
  • services.json - Manual services and NPM overrides
  • categories.json - Category definitions
  • passkeys.json - WebAuthn passkey credentials
  • branding/ - Custom logo uploads

Important: Back up this directory regularly!

Nginx Proxy Manager Integration

How do I set up NPM integration?

  1. Create a read-only NPM user (see below)
  2. Configure in Admin Panel:
    • Go to Admin Panel → Configuration
    • Enable "Nginx Proxy Manager Integration"
    • Enter your NPM URL (e.g., http://nginx-proxy-manager:81)
    • Enter the read-only user's email and password
    • Click "Save Configuration"

How do I create a read-only user in Nginx Proxy Manager?

Using NPM UI (Recommended)

  1. Log in to NPM admin panel
  2. Go to Users → Add User
  3. Fill in the details:
    • Email: services-dashboard@local (or any email)
    • Name: Services Dashboard (Read Only)
    • Password: Generate a strong password
  4. Important: Do NOT give the user admin privileges
  5. Click Save

Security Note: A standard NPM user (non-admin) can only view and manage their own proxy hosts. For Services Dashboard, create a dedicated user with minimal permissions.

Why aren't my NPM services showing up?

Check these common issues:

  1. NPM URL is incorrect

    • Use the internal Docker network URL: http://nginx-proxy-manager:81
    • Don't use localhost from inside Docker
    • Make sure the NPM API is accessible without a third-party authentication tool if running accessing via an NPM host.

  2. Credentials are wrong

    • Verify email and password in NPM
    • Check for typos

  3. NPM is not accessible

    • Ensure both containers are on the same Docker network if accessing via a docker network

  4. NPM integration is disabled

    • Check Admin Panel → Configuration
    • Ensure "Enable NPM Integration" is checked

  5. Check Docker logs:

    docker logs services-dashboard

    Look for NPM connection errors

Can I use external NPM instances?

Yes, but ensure:

  • The NPM URL is accessible from the Services Dashboard container
  • Firewall rules allow the connection
  • Use HTTPS if exposing NPM publicly

Categories

How do categories work?

Categories are automatically detected from:

  1. Icon metadata (from dashboard-icons or simple-icons)
  2. Service name matching (pre-defined application names and categories)
  3. Manual assignment (via admin panel)

Why is everything showing up in "Other"?

Services appear in "Other" when:

  • They have no categories assigned
  • All their categories are hidden in the admin panel
  • Auto-detection failed

To fix:

  1. Go to Admin Panel → Services
  2. Click "Customize" or "Edit" on the service
  3. Click "Browse" under Categories
  4. Select appropriate categories

How do I hide/show categories?

  1. Go to Admin Panel → Category Management
  2. Find the category you want to hide
  3. Click "Hide" (or "Show" to make it visible again)

Hidden categories won't appear in the main dashboard sidebar.

Can I rename categories?

Yes! In the Admin Panel → Category Management:

  1. Click "Rename" on any category
  2. Enter a new display name
  3. The original category name is preserved for matching

What's the difference between "configured" and "auto-detected" categories?

  • Auto-detected: Automatically created from services, can be hidden but not deleted
  • Configured: Manually created or modified, can be fully managed and deleted

Icons

How do I search for icons?

The icon browser supports fuzzy matching:

  • homeassistant finds "Home Assistant"
  • home-assistant finds "Home Assistant"
  • home assistant finds "Home Assistant"

All variations work regardless of spaces, hyphens, or underscores.

Where do icons come from?

Two sources:

  1. Dashboard Icons (>2250 icons) - from dashboard-icons
  2. Simple Icons (>3350 icons) - from simple-icons

Why are some icons black in dark mode?

Simple Icons are converted to white automatically. If you see black icons:

  1. Clear your browser cache
  2. Hard refresh (Ctrl+Shift+R or Cmd+Shift+R)
  3. Update to the latest version

How do I use custom icons?

Currently, custom icon uploads aren't supported. You can:

  1. Use icons from the 3500+ available in the browser
  2. Reference external URLs by entering its full URL

Icon search shows "0 icons" - what's wrong?

  1. Check browser console for errors
  2. Restart the container: 
    docker restart services-dashboard
  3. Verify icon metadata loaded: 
    docker logs services-dashboard | grep "icons"
    Should see: ✓ Loaded X dashboard icons and ✓ Loaded X simple-icons

Performance & Troubleshooting

The dashboard is slow to load

Common causes:

  1. Too many services

    • Consider hiding unused services
    • Use categories to organize

  2. NPM with many hosts

    • NPM fetching can be slow

  3. Network issues

    • Check NPM connectivity
    • Use internal Docker networks instead of localhost

Services aren't updating after changes

  1. Hard refresh your browser (Ctrl+Shift+R or Cmd+Shift+R)
  2. Clear browser cache
  3. Check if changes saved:
    • Verify in ./data/services.json or ./data/config.json

Categories.json is corrupted

Symptoms:

SyntaxError: Unexpected non-whitespace character after JSON

Fix:

  1. Stop the container
  2. Backup ./data/categories.json
  3. Fix JSON syntax or replace with: 
    []
  4. Restart the container

The system will auto-recreate categories from services.

Race condition errors in logs

If you see repeated JSON parsing errors:

  1. Update to the latest version
  2. Clear ./data/categories.json and restart

Security

Is the admin panel secure?

Security measures:

  • CSRF protection on all write operations
  • Session-based authentication
  • Rate limiting on API endpoints
  • WebAuthn/Passkey support

Best practices:

  1. Always set ADMIN_USERNAME and ADMIN_PASSWORD
  2. Use passkeys for passwordless authentication
  3. Don't expose admin panel to public internet without a reverse proxy
  4. Use HTTPS in production
  5. Keep Docker images updated

Should I expose this to the internet?

Main dashboard (port 3000): Can be exposed - it's read-only

Admin panel (port 3001):

  • ⚠️ Not recommended without additional security
  • If you must:
    • Use strong authentication
    • Enable passkeys
    • Use HTTPS with valid certificates
    • Consider VPN access instead

How do I set up passkey authentication?

  1. Go to Admin Panel → Passkey Management
  2. Click "Add Passkey"
  3. Enter a name (e.g., "My Laptop")
  4. Follow your browser's prompts to register
  5. Use your passkey to log in instead of password

Benefits:

  • More secure than passwords
  • Resistant to phishing
  • Biometric authentication support

What data is collected?

None. Services Dashboard:

  • Doesn't track usage
  • Doesn't send telemetry
  • Doesn't require internet access
  • All data stays on your server

Common Error Messages

"Failed to load services from API"

Causes:

  • Backend server not running
  • Port 3000 not accessible

Fix:

docker logs services-dashboard
docker restart services-dashboard

"CSRF token mismatch"

Causes:

  • Session expired
  • Browser cached old token

Fix:

  1. Hard refresh browser (Ctrl+Shift+R)
  2. Clear cookies for the site
  3. Log in again

Migration & Updates

How do I update to the latest version?

Docker (recommended):

docker pull b12e/services-dashboard:latest
docker-compose down
docker-compose up -d

Your data is preserved in the ./data volume.

Will my data be lost when updating?

No! As long as you use Docker volumes or bind mounts, your data persists across updates.

Always backup before major updates:

cp -r ./data ./data-backup-$(date +%Y%m%d)

Getting Help

Where can I get support?

  1. GitHub Issues: https://github.com/b12e/selfhosted-shortcuts/issues
  2. Check this FAQ for common issues
  3. Docker logs: docker logs services-dashboard
  4. Browser console: Check for JavaScript errors

How do I report a bug?

Include:

  1. Version: Check Docker image tag or commit hash
  2. Environment: Docker/manual, OS, browser
  3. Steps to reproduce
  4. Logs: Docker logs and browser console
  5. Expected vs actual behavior

How do I request a feature?

Open a GitHub issue with:

  • Clear description of the feature
  • Use case/problem it solves
  • Any relevant examples or mockups

Advanced Configuration

Can I customize the theme?

Currently, dark theme is the only option.

How do I backup my data?

Automated backup script:

#!/bin/bash
BACKUP_DIR="/backups/services-dashboard"
DATE=$(date +%Y%m%d-%H%M%S)

# Create backup
tar -czf "$BACKUP_DIR/backup-$DATE.tar.gz" ./data

# Keep only last 7 backups
ls -t "$BACKUP_DIR"/*.tar.gz | tail -n +8 | xargs rm -f

Run this daily via cron.

Troubleshooting Checklist

Before opening an issue, try:

  • Hard refresh browser (Ctrl+Shift+R)
  • Clear browser cache and cookies
  • Restart Docker container
  • Check Docker logs for errors
  • Verify data files aren't corrupted (valid JSON)
  • Update to latest version
  • Check this FAQ
  • Review GitHub issues for similar problems

Last updated: 2025-01-22 Version: 1.0.0

Clone this wiki locally