vndangkhoa/kv-music
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
kv-music/self-hosted-database.md
SamidyFR 48937ed573 style: auto-fix linting issues
2026-02-19 13:55:31 +00:00

9 KiB
Raw Blame History

Self-Hosted Database Setup Guide

This guide will show you how to set up your own authentication system and database for Monochrome accounts.

⚠️ Note: You will need to enter the same configurations on each device where you want to use your custom database.

Table of Contents

Prerequisites

Before starting, ensure you have:

  • A computer to host the database (can also use a VPS)
  • A Firebase account (for authentication only)
  • PocketBase installed on your host machine
  • A domain name (free options available at DigitalPlat)

💡 This guide assumes you're setting everything up on your local machine. The process is identical for a VPS.

Step 1: Setup Firebase Authentication

1.1 Create a Firebase Project

  1. Go to the Firebase Console
  2. Create a new project
  3. On the left sidebar, click Build → Authentication
  4. Click Get Started

1.2 Enable Sign-in Methods

  1. Go to the Sign-in method tab
  2. Enable Google and Email providers
  3. Set your project support email
  4. Click Save

1.3 Authorize Your Domain

Firebase requires authorized domains for authentication:

  1. In Authentication → Settings → Authorized domains
  2. Click Add domain
  3. Add your hosting domain:
    • If using the official Monochrome site: monochrome.samidy.com or your preferred mirror (e.g., monochrome.tf)
    • If self-hosting the website: add your custom domain

💡 localhost is usually added by default for local testing. You can leave this enabled.

Step 2: PocketBase Setup

2.1 Install and Configure

  1. Download PocketBase and follow their setup guide
  2. Access the PocketBase Admin UI (typically at http://127.0.0.1:8090/_/)

2.2 Create Collections

Create two collections: DB_users and public_playlists (do NOT use the default "users" collection)

DB_users Fields

Field Name Type Description
firebase_id Plain Text Links to Firebase user ID
lastUpdated Number Timestamp of last update
history JSON User listening history
library JSON User's saved library
user_playlists JSON User's custom playlists
user_folders JSON User's playlist folders
deleted_playlists JSON Soft-deleted playlists
username Plain Text Unique username
display_name Plain Text Profile display name
avatar_url URL Profile avatar URL
banner URL Profile banner URL
status Plain Text User status
about Plain Text About me bio
website URL Personal website URL
lastfm_username Plain Text Last.fm username
privacy JSON Privacy settings
profile_data_source Select (lastfm) Preferred data source for profile
favorite_albums JSON User's favorite albums

public_playlists Fields

Field Name Type Description
firebase_id Plain Text Creator's Firebase user ID
addedAt Number Creation timestamp
numberOfTracks Number Total track count
OriginalId Plain Text Original playlist ID
publishedAt Number Publication timestamp
title Plain Text Playlist title
uid Plain Text Unique identifier
uuid Plain Text UUID for the playlist
tracks JSON Playlist tracks data
image URL Playlist cover image

2.3 Configure API Rules

Set the API rules for both collections to allow read/write access:

DB_users API Rules:

  • List/Search Rule: firebase_id = @request.query.f_id || username != ""
  • View Rule: firebase_id = @request.query.f_id || username != ""
  • Create Rule: firebase_id = @request.query.f_id
  • Update Rule: firebase_id = @request.query.f_id
  • Delete Rule: firebase_id = @request.query.f_id

public_playlists API Rules:

  • List/Search Rule: uuid = @request.query.p_id
  • View Rule: id != ""
  • Create Rule: firebase_id = @request.query.f_id
  • Update Rule: uid = @request.query.f_id
  • Delete Rule: uid = @request.query.f_id

Step 3: Cloudflare Tunnel Setup

To make your PocketBase instance accessible from other devices securely:

3.1 Create a Cloudflare Account

  1. Sign up at the Cloudflare Dashboard
  2. Set up Zero Trust (free plan available)

3.2 Create a Tunnel

  1. In the Cloudflare dashboard, go to Zero Trust → Networks → Connectors
  2. Select Cloudflared
  3. Give your tunnel a name (e.g., monochrome-database)
  4. Follow the installation guide for your operating system

3.3 Configure Hostname

  1. In the tunnel setup, add a Public Hostname
  2. Subdomain: Choose a subdomain (e.g., db for db.yourdomain.com)
  3. Domain: Select your domain from the dropdown
  4. Service: Select HTTP
  5. URL: Enter your PocketBase local address (e.g., 127.0.0.1:8090)

⚠️ Note: Cloudflare requires a valid domain. Free .pages.dev domains won't work for this. Get a free domain at DigitalPlat.

  1. Save the configuration

Your database will now be accessible at your chosen domain!

Step 4: Getting Configurations

4.1 Get Firebase Configuration

  1. In the Firebase Console, open your project
  2. Click the ⚙️ Settings icon next to "Project Overview"
  3. Select Project settings
  4. In the General tab, scroll to "Your apps"
  5. Click the Web icon (</>)
  6. Register your app (e.g., "Monochrome Auth")
  7. Copy the firebaseConfig object:
const firebaseConfig = {
    apiKey: 'AIzaSy...',
    authDomain: 'your-project.firebaseapp.com',
    databaseURL: 'https://your-project.firebaseio.com',
    projectId: 'your-project',
    storageBucket: 'your-project.appspot.com',
    messagingSenderId: '...',
    appId: '...',
};

⚠️ Copy only the object content inside the curly braces { ... }

4.2 Get Database URL

Simply copy your PocketBase domain from Cloudflare (e.g., https://db.yourdomain.com)

Step 5: Linking with Monochrome

Now configure Monochrome to use your custom backend:

  1. Open Monochrome in your browser
  2. Go to Settings (gear icon)
  3. Click ADVANCED: Custom Account Database
  4. Enter your configurations:
    • Database Config: Your PocketBase domain (e.g., https://db.yourdomain.com)
    • Authentication Config: The Firebase config JSON object from Step 4.1
  5. Click Save

✅ Done! Your Monochrome instance is now connected to your custom database.

📝 Important: Repeat Step 5 on every device where you want to use your custom database.

Troubleshooting

Cannot sign in

  • Ensure your domain is added to Firebase's authorized domains
  • Check that the Firebase config JSON is correctly formatted

Database connection errors

  • Verify your Cloudflare tunnel is running
  • Check that PocketBase is accessible at your domain
  • Ensure API rules are configured correctly

Data not syncing

  • Make sure you're signed in with the same account on all devices
  • Check the browser console for error messages
  • Verify your database collections have the correct fields

Security Tips

  • Keep your Firebase API key secure (it's okay to expose it for client-side auth, but don't share it unnecessarily)
  • Regularly backup your PocketBase database
  • Use strong, unique passwords for your Cloudflare and Firebase accounts
  • Consider enabling 2FA on all accounts

Need Help?