kv-music/self-hosted-database.md

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
• Step 1: Setup Firebase Authentication
• Step 2: PocketBase Setup
• Step 3: Cloudflare Tunnel Setup
• Step 4: Getting Configurations
• Step 5: Linking with Monochrome
• Troubleshooting

---

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

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
• View Rule: firebase_id = @request.query.f_id
• 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.

6. 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?

• Join our Discord community (if available)
• Open an issue on GitHub
• Check existing GitHub issues for solutions