From f249cd4ce0d4a1309b70f655062da36719b6e5d7 Mon Sep 17 00:00:00 2001 From: Eduard Prigoana Date: Wed, 4 Feb 2026 19:20:27 +0200 Subject: [PATCH] AIslop reames --- CONTRIBUTE.md | 310 ++++++++++++++++++++++++++++++++++------ INSTANCES.md | 120 ++++++++++++---- README.md | 222 +++++++++++++++++++++++----- license | 233 ++++++++++++++++++++++++++++++ self-hosted-database.md | 275 +++++++++++++++++++++++++---------- 5 files changed, 980 insertions(+), 180 deletions(-) create mode 100644 license diff --git a/CONTRIBUTE.md b/CONTRIBUTE.md index 03f4cf9..562e09d 100644 --- a/CONTRIBUTE.md +++ b/CONTRIBUTE.md @@ -1,75 +1,303 @@ -# Development +# Contributing to Monochrome -This project uses [Vite](https://vitejs.dev/) for local development and optimized builds. +Thank you for your interest in contributing to Monochrome! This guide will help you get started with development, understand our codebase, and follow our contribution workflow. + +--- + +## Table of Contents + +- [Development Setup](#development-setup) +- [Code Quality](#code-quality) +- [Project Structure](#project-structure) +- [Contributing Workflow](#contributing-workflow) +- [Commit Message Guidelines](#commit-message-guidelines) +- [Deployment](#deployment) +- [Questions?](#questions) + +--- + +## Development Setup ### Prerequisites - [Node.js](https://nodejs.org/) (Version 20+ or 22+ recommended) -- [Bun](https://bun.sh/) (or [npm](https://www.npmjs.com/)) +- [Bun](https://bun.sh/) (preferred) or [npm](https://www.npmjs.com/) -### Getting Started +### Quick Start + +1. **Fork and clone the repository:** + + ```bash + git clone https://github.com/YOUR_USERNAME/monochrome.git + cd monochrome + ``` + +2. **Install dependencies:** -1. Install dependencies: ```bash bun install + # or + npm install ``` -2. Start the development server: + +3. **Start the development server:** + ```bash bun run dev + # or + npm run dev ``` - The app will be available at `http://localhost:5173/`. -### Why Vite? +4. **Open your browser:** + Navigate to `http://localhost:5173/` -- **Instant Updates**: Support for Hot Module Replacement (HMR) means changes to JS/CSS are reflected instantly in the browser. -- **Dependency Management**: No more manual path tracking or broken internal imports. -- **Automated PWA**: Service Worker generation and asset hashing are handled automatically. +--- -## Code Quality & Linting +## Code Quality -We use a standard stack to ensure code quality and consistency: +We maintain high code quality standards. All code must pass our linting checks before being merged. -- **JS**: [ESLint](https://eslint.org/) -- **CSS**: [Stylelint](https://stylelint.io/) -- **HTML**: [HTMLHint](https://htmlhint.com/) -- **Formatting**: [Prettier](https://prettier.io/) +### Our Tool Stack -### Commands +| Tool | Purpose | Files | +| ---------------------------------- | ------------------ | -------- | +| [ESLint](https://eslint.org/) | JavaScript linting | `*.js` | +| [Stylelint](https://stylelint.io/) | CSS linting | `*.css` | +| [HTMLHint](https://htmlhint.com/) | HTML validation | `*.html` | +| [Prettier](https://prettier.io/) | Code formatting | All | -- **Check everything:** `bun run lint` -- **Auto-format code:** `bun run format` (Runs Prettier) -- **Fix JS issues:** `bun run lint:js -- --fix` -- **Fix CSS issues:** `bun run lint:css -- --fix` +### Available Commands -> [!IMPORTANT] -> A GitHub Action automatically runs these checks on every push and pull request. Please ensure `bun run lint` passes before committing. +```bash +# Check everything (runs all linters) +bun run lint + +# Auto-format all code +bun run format + +# Fix JavaScript issues automatically +bun run lint:js -- --fix + +# Fix CSS issues automatically +bun run lint:css -- --fix + +# Check HTML +bun run lint:html + +# Check specific file types +bun run lint:js +bun run lint:css +``` + +> ⚠️ **Important:** A GitHub Action automatically runs `bun run lint` on every push and pull request. Please ensure all checks pass before committing. + +--- ## Project Structure -- `/js`: Application source code. -- `/public`: Static assets (images, manifest, instances.json) that are copied directly to the build folder. -- `index.html`: The entry point of the application. -- `vite.config.js`: Build and PWA configuration. +``` +monochrome/ +├── 📁 js/ # Application source code +│ ├── components/ # UI components +│ ├── utils/ # Utility functions +│ ├── api/ # API integration +│ └── ... +├── 📁 public/ # Static assets +│ ├── assets/ # Images, icons, fonts +│ ├── manifest.json # PWA manifest +│ └── instances.json # API instances configuration +├── 📄 index.html # Application entry point +├── 📄 vite.config.js # Build and PWA configuration +├── 📄 package.json # Dependencies and scripts +└── 📄 README.md # Project documentation +``` -## Commit Messages +### Key Directories -We use conventional Formatting for our commits, and we encourage you to do the same when contributing. +- **`/js`** - All JavaScript source code + - Keep modules focused and single-purpose + - Use ES6+ features + - Add JSDoc comments for complex functions -#### Examples +- **`/public`** - Static assets copied directly to build + - Images should be optimized before adding + - Keep file sizes reasonable + - Use appropriate formats (WebP where possible) -- "feat(playlists): shuffle playlist" -- "fix(metadata): Hi-res Corrupted Metadata" -- "refactor(downloading): refactor cancelling downloads" -- "docs(README): Capitalization Improvements" -- "chore(packages): bump up lyrics package version due to vulnerability" +--- -A Cheatsheet For This Can Be Found [Here](https://gist.github.com/Zekfad/f51cb06ac76e2457f11c80ed705c95a3). +## Contributing Workflow + +### 1. Create a Branch + +```bash +git checkout -b feature/your-feature-name +# or +git checkout -b fix/description-of-fix +``` + +### 2. Make Your Changes + +- Follow existing code style +- Write clear, self-documenting code +- Add comments for complex logic +- Update documentation if needed + +### 3. Test Your Changes + +```bash +# Run all linters +bun run lint + +# Test the build +bun run build +``` + +### 4. Commit Your Changes + +Follow our [commit message guidelines](#commit-message-guidelines). + +```bash +git add . +git commit -m "feat(player): add keyboard shortcut for loop toggle" +``` + +### 5. Push and Create a Pull Request + +```bash +git push origin feature/your-feature-name +``` + +Then open a pull request on GitHub with: + +- Clear title describing the change +- Detailed description of what changed and why +- Reference any related issues + +--- + +## Commit Message Guidelines + +We use [Conventional Commits](https://www.conventionalcommits.org/) for clear, structured commit messages. + +### Format + +``` +(): + +[optional body] + +[optional footer] +``` + +### Types + +| Type | Description | +| ---------- | ------------------------------------------------- | +| `feat` | New feature | +| `fix` | Bug fix | +| `docs` | Documentation changes | +| `style` | Code style changes (formatting, semicolons, etc.) | +| `refactor` | Code refactoring without changing behavior | +| `perf` | Performance improvements | +| `test` | Adding or updating tests | +| `chore` | Maintenance tasks (dependencies, build, etc.) | + +### Scopes + +Common scopes in our project: + +- `player` - Audio player functionality +- `ui` - User interface components +- `api` - API integration +- `library` - Library management +- `playlists` - Playlist functionality +- `lyrics` - Lyrics display +- `downloads` - Download functionality +- `auth` - Authentication +- `pwa` - Progressive Web App features +- `settings` - Settings/preferences +- `theme` - Theming system + +### Examples + +```bash +# Feature addition +feat(playlists): add shuffle playlist button + +# Bug fix +fix(metadata): resolve corrupted Hi-res metadata issue + +# Refactoring +refactor(downloads): simplify cancel download logic + +# Documentation +docs(README): improve installation instructions + +# Maintenance +chore(deps): bump lyrics package to fix vulnerability + +# Style changes +style(player): fix indentation in audio controls +``` + +### Tips + +- Use the present tense ("add feature" not "added feature") +- Use imperative mood ("move cursor to..." not "moves cursor to...") +- Don't capitalize the first letter +- No period at the end +- Keep the first line under 72 characters + +📋 **Cheat Sheet:** [Conventional Commits Cheat Sheet](https://gist.github.com/Zekfad/f51cb06ac76e2457f11c80ed705c95a3) + +--- ## Deployment -Deployment is automated via **Cloudflare Pages**. +Deployment is fully automated via **Cloudflare Pages**. -> [!NOTE] -> The project uses a relative base path (`./`) in `vite.config.js`. This allows the exact same build artifact to work on both **Cloudflare Pages** (served from root) and **GitHub Pages** (served from `/monochrome/`), provided that Hash Routing is used. +### How It Works -Simply push your changes to the `main` branch. +1. Push changes to the `main` branch +2. Cloudflare automatically builds and deploys +3. Changes are live within minutes + +### Configuration Notes + +The project uses a **relative base path** (`./`) in `vite.config.js`. This allows the same build artifact to work on both: + +- **Cloudflare Pages** (served from root) +- **GitHub Pages** (served from `/monochrome/`) + +Hash routing is used to ensure compatibility across all hosting platforms. + +### Manual Deployment + +If you need to deploy manually: + +```bash +# Build for production +bun run build + +# The `dist/` folder contains the deployable files +``` + +--- + +## Questions? + +- 💬 Join our community discussions +- 🐛 Open an issue for bugs or feature requests +- 📧 Contact the maintainers + +--- + +## Code of Conduct + +- Be respectful and inclusive +- Welcome newcomers and help them learn +- Focus on constructive feedback +- Respect different viewpoints and experiences + +Thank you for contributing to Monochrome! diff --git a/INSTANCES.md b/INSTANCES.md index 6a3739f..5385690 100644 --- a/INSTANCES.md +++ b/INSTANCES.md @@ -1,25 +1,95 @@ -API: -| Provider | Instance URL | -|----------------|---------------------------------| -| Monochrome | https://monochrome-api.samidy.com ([NOTE](https://rentry.co/monochromeapi)) | -| squid.wtf | https://triton.squid.wtf | -| Lucida (QQDL) | https://wolf.qqdl.site | -| | https://maus.qqdl.site | -| | https://vogel.qqdl.site | -| | https://katze.qqdl.site | -| | https://hund.qqdl.site | -| Spotisaver | https://hifi-one.spotisaver.net | -| | https://hifi-two.spotisaver.net | -| Kinoplus | https://tidal.kinoplus.online | -| Binimum | https://tidal-api.binimum.org | - -UI: -| Provider | Instance URL | -|-------------------|------------------------------------| -| Monochrome | https://monochrome.samidy.com | -| tidal-ui (bini) | https://music.binimum.org | -| squid.wtf | https://tidal.squid.wtf | -| QQDL | https://tidal.qqdl.site/ | -| Arjix | https://music.arjix.dev/ | -| Spofree | https://spo.free.nf | -| Mappl | https://mappl.tv/music | +# Monochrome Instances + +This document lists public instances of Monochrome that you can use. Instances are community-hosted versions of Monochrome that provide access to the application. + +> 💡 **Tip:** If you want to self-host your own instance, see our [Self-Hosting Guide](self-hosted-database.md). + +--- + +## Official Instance + +The official Monochrome instance maintained by the core team: + +| URL | Status | Notes | +| ------------------------------------------------------ | ----------- | ---------------- | +| [monochrome.tf](https://monochrome.tf) | Official | Primary instance | +| [monochrome.samidy.com](https://monochrome.samidy.com) | Official | Secondary mirror | + +--- + +## Community Instances + +### UI-Only Instances + +These instances provide the tidal-ui web interface, not monochrome: + +| Provider | URL | Status | +| ------------------- | ---------------------------------------------- | --------- | +| **bini (tidal-ui)** | [music.binimum.org](https://music.binimum.org) | Community | +| **squid.wtf** | [tidal.squid.wtf](https://tidal.squid.wtf) | Community | +| **QQDL** | [tidal.qqdl.site](https://tidal.qqdl.site/) | Community | + +--- + +## API Instances + +Monochrome uses the Hi-Fi API under the hood. These are available API endpoints that can be used with Monochrome or other Hi-Fi based applications: + +### Official & Community APIs + +| Provider | URL | Notes | +| ----------------- | ----------------------------------- | ---------------------------------------------------------- | +| **Monochrome** | `https://monochrome-api.samidy.com` | Official API - [See Note](https://rentry.co/monochromeapi) | +| **squid.wtf** | `https://triton.squid.wtf` | Community hosted | +| **Lucida (QQDL)** | `https://wolf.qqdl.site` | Community hosted | +| | `https://maus.qqdl.site` | Community hosted | +| | `https://vogel.qqdl.site` | Community hosted | +| | `https://katze.qqdl.site` | Community hosted | +| | `https://hund.qqdl.site` | Community hosted | +| **Spotisaver** | `https://hifi-one.spotisaver.net` | Community hosted | +| | `https://hifi-two.spotisaver.net` | Community hosted | +| **Kinoplus** | `https://tidal.kinoplus.online` | Community hosted | +| **Binimum** | `https://tidal-api.binimum.org` | Community hosted | + +--- + +## Instance Health + +To check the current status of instances: + +1. Visit the instance URL in your browser +2. Check if the page loads correctly +3. Try playing a track to verify API connectivity + +> **Note:** Community instances may have varying uptime and performance. If one doesn't work, try another. + +--- + +## Adding Your Instance + +Want to add your instance to this list? + +1. Ensure your instance is stable and publicly accessible +2. Open a pull request with your instance details +3. Include: + - Instance URL + - Provider name + - Type (UI/API/Both) + - Brief description + +--- + +## Disclaimer + +- Community instances are not affiliated with the official Monochrome project +- Use at your own risk +- Instance availability and performance may vary +- The official project does not guarantee uptime for community instances + +--- + +## Related Resources + +- [Self-Hosting Guide](self-hosted-database.md) - Host your own instance +- [Contributing Guide](CONTRIBUTE.md) - Contribute to the project +- [Main Repository](https://github.com/SamidyFR/monochrome) - Source code diff --git a/README.md b/README.md index db690f2..5ba4459 100644 --- a/README.md +++ b/README.md @@ -6,46 +6,198 @@

Monochrome

-### **Monochrome** is an open-source, privacy-respecting, ad-free [TIDAL](https://tidal.com) web UI, built on top of [Hi-Fi](https://github.com/sachinsenal0x64/hifi). +

+ An open-source, privacy-respecting, ad-free music app. +

-
+

+ Live Demo • + Donate • + Features • + Installation • + Usage • + Self-Hosting • + Contributing +

-[Monochrome UI](https://monochrome.samidy.com/#album/413189044) +

+ + GitHub stars + + + GitHub forks + + + GitHub issues + +

-### Features +--- -
    -
  • High-quality Hi-Res/lossless audio streaming
    • -
  • Lyrics support with karaoke mode
    • -
  • Recently Played tracking for easy history access
    • -
  • Comprehensive Personal Library for favorites
    • -
  • Intelligent API caching for improved performance
    • -
  • Offline-capable Progressive Web App (PWA)
    • -
  • Media Session API integration for system controls
    • -
  • Queue management with shuffle and repeat modes
    • -
  • Track downloads with automatic metadata embedding
    • -
  • Multiple API instance support with failover
    • -
  • Dark, minimalist interface optimized for focus
    • -
  • Customizable themes
    • -
  • Keyboard shortcuts for power users
    • -
  • Accurate and unique audio visualizer
    • -
  • Account system for cross-device syncing
    • -
  • Genius integration for lyrics
    • -
  • Last.fm and ListenBrainz integration for scrobbling
    • -
  • Unreleased music from ArtistGrid
    • -
  • Dynamic Discord Embeds
    • -
  • Smart recommendations for new songs, albums & artists
    • -
  • Support for local music files
    • -
  • Playlist import from other platforms
    • -
  • Public playlists for social sharing
    • -
+## What is Monochrome? -### Check it out live at: [**monochrome.tf**](https://monochrome.tf) +**Monochrome** is an open-source, privacy-respecting, ad-free [TIDAL](https://tidal.com) web UI, built on top of [Hi-Fi](https://github.com/binimum/hifi-api). It provides a beautiful, minimalist interface for streaming high-quality music without the clutter of traditional streaming platforms. -
+

+ + Monochrome UI + +

-[![GitHub stars](https://img.shields.io/github/stars/SamidyFR/monochrome?style=for-the-badge&color=ffffff&labelColor=000000)](https://github.com/SamidyFR/monochrome/stargazers) -[![GitHub forks](https://img.shields.io/github/forks/SamidyFR/monochrome?style=for-the-badge&color=ffffff&labelColor=000000)](https://github.com/SamidyFR/monochrome/forks) -[![GitHub issues](https://img.shields.io/github/issues/SamidyFR/monochrome?style=for-the-badge&color=ffffff&labelColor=000000)](https://github.com/SamidyFR/monochrome/issues) +--- -[As seen on FMHY](https://fmhy.net/audio#streaming-sites) +## Features + +### Audio Quality + +- High-quality Hi-Res/lossless audio streaming +- Support for local music files +- Intelligent API caching for improved performance + +### Interface + +- Dark, minimalist interface optimized for focus +- Customizable themes +- Accurate and unique audio visualizer +- Offline-capable Progressive Web App (PWA) +- Media Session API integration for system controls + +### Library & Organization + +- Recently Played tracking for easy history access +- Comprehensive Personal Library for favorites +- Queue management with shuffle and repeat modes +- Playlist import from other platforms +- Public playlists for social sharing +- Smart recommendations for new songs, albums & artists + +### Lyrics & Metadata + +- Lyrics support with karaoke mode +- Genius integration for lyrics +- Track downloads with automatic metadata embedding + +### Integrations + +- Account system for cross-device syncing +- Last.fm and ListenBrainz integration for scrobbling +- Unreleased music from [ArtistGrid](https://artistgrid.cx) +- Dynamic Discord Embeds +- Multiple API instance support with failover + +### Power User Features + +- Keyboard shortcuts for power users + +--- + +## Quick Start + +### Live Instance + +The easiest way to try Monochrome is through our official instance: + +**[monochrome.tf](https://monochrome.tf)** + +For alternative instances, check [INSTANCES.md](INSTANCES.md). + +--- + +## Installation + +### Prerequisites + +- [Node.js](https://nodejs.org/) (Version 20+ or 22+ recommended) +- [Bun](https://bun.sh/) or [npm](https://www.npmjs.com/) + +### Local Development + +1. **Clone the repository:** + + ```bash + git clone https://github.com/SamidyFR/monochrome.git + cd monochrome + ``` + +2. **Install dependencies:** + + ```bash + bun install + # or + npm install + ``` + +3. **Start the development server:** + + ```bash + bun run dev + # or + npm run dev + ``` + +4. **Open your browser:** + Navigate to `http://localhost:5173/` + +### Building for Production + +```bash +bun run build +# or +npm run build +``` + +--- + +## Usage + +### Basic Usage + +1. Visit the [live instance](https://monochrome.tf) or your local development server +2. Search for your favorite artists, albums, or tracks +3. Click play to start streaming +4. Use the media controls to manage playback, queue, and volume + +### Keyboard Shortcuts + +| Shortcut | Action | +| -------- | -------------- | +| `Space` | Play/Pause | +| `→` | Next track | +| `←` | Previous track | +| `↑` | Volume up | +| `↓` | Volume down | +| `M` | Mute/Unmute | +| `L` | Toggle lyrics | +| `F` | Fullscreen | +| `/` | Focus search | + +### Account Features + +To sync your library, history, and playlists across devices: + +1. Click the profile icon in the top right +2. Sign in with Google or Email +3. Your data will automatically sync across all devices + +--- + +## Contributing +We welcome contributions from the community! Please see our [Contributing Guide](CONTRIBUTE.md) for: + +- Setting up your development environment +- Code style and linting +- Project structure +- Commit message conventions +- Deployment information + +--- + +

+ + As seen on FMHY + +

+ +

+ Made with ❤️ by the Monochrome team +

diff --git a/license b/license new file mode 100644 index 0000000..dbf39b2 --- /dev/null +++ b/license @@ -0,0 +1,233 @@ +# HIPPOCRATIC LICENSE + +**Version 3.0, October 2021** +**Modified 2025-08-04** + + + +--- + +## TERMS AND CONDITIONS + +### TERMS AND CONDITIONS FOR USE, COPY, MODIFICATION, PREPARATION OF DERIVATIVE WORK, REPRODUCTION, AND DISTRIBUTION: + +--- + +## [1.] DEFINITIONS + +_This section defines certain terms used throughout this license agreement._ + +- **[1.1.]** “License” means the terms and conditions, as stated herein, for use, copy, modification, preparation of derivative work, reproduction, and distribution of Software (as defined below). +- **[1.2.]** “Licensor” means the copyright and/or patent owner or entity authorized by the copyright and/or patent owner that is granting the License. +- **[1.3.]** “Licensee” means the individual or entity exercising permissions granted by this License, including the use, copy, modification, preparation of derivative work, reproduction, and distribution of Software (as defined below). +- **[1.4.]** “Software” means any copyrighted work, including but not limited to software code, authored by Licensor and made available under this License, and includes all forms, formats, translations, transformations, compilations, or representations of the original work, whether human- or machine-readable, and any data, output, result, or derivative generated by or from the Software. +- **[1.5.]** “Supply Chain” means the sequence of processes involved in the production and/or distribution of a commodity, good, or service offered by the Licensee. +- **[1.6.]** “Supply Chain Impacted Party” or “Supply Chain Impacted Parties” means any person(s) directly impacted by any of Licensee’s Supply Chain, including the practices of all persons or entities within the Supply Chain prior to a good or service reaching the Licensee. +- **[1.7.]** “Duty of Care” is defined by its use in tort law, delict law, and/or similar bodies of law closely related to tort and/or delict law, including without limitation, a requirement to act with the watchfulness, attention, caution, and prudence that a reasonable person in the same or similar circumstances would use towards any Supply Chain Impacted Party. +- **[1.8.]** “Worker” is defined to include any and all permanent, temporary, and agency workers, as well as piece-rate, salaried, hourly paid, legal young (minors), part-time, night, and migrant workers. +- **[1.9.]** “Dataset” means any collection, corpus, compilation, aggregation, or aggregation of data, code, text, software, or other materials, in whole or in part, used for any purpose related to artificial intelligence (AI) or machine learning (ML), including but not limited to training, fine-tuning, evaluating, testing, benchmarking, or developing AI/ML models, systems, or services. +- **[1.10.]** “Automated Means” includes, but is not limited to, any current or future automated, semi-automated, or programmatic method, tool, or technology, whether known or unknown at the time of this License, used to access, copy, download, or acquire data or code. + +--- + +## [2.] INTELLECTUAL PROPERTY GRANTS + +_This section identifies intellectual property rights granted to a Licensee._ + +- **[2.1.] Grant of Copyright License:** + Subject to the terms and conditions of this License, Licensor hereby grants to Licensee a worldwide, non-exclusive, no-charge, royalty-free copyright license to use, copy, modify, prepare derivative work, reproduce, or distribute the Software, Licensor authored modified software, or other work derived from the Software. + +- **[2.2.] Grant of Patent License:** + Subject to the terms and conditions of this License, Licensor hereby grants Licensee a worldwide, non-exclusive, no-charge, royalty-free patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer Software. + +--- + +## [3.] ETHICAL STANDARDS + +_This section lists conditions the Licensee must comply with in order to have rights under this License._ + +The rights granted to the Licensee by this License are expressly made subject to the Licensee’s ongoing compliance with the following conditions: + +### [3.1.] The Licensee SHALL NOT, whether directly or indirectly, through agents or assigns: + +- [3.1.1.] Infringe upon any person’s right to life or security of person, engage in extrajudicial killings, or commit murder, without lawful cause (See Article 3, _United Nations Universal Declaration of Human Rights_; Article 6, _International Covenant on Civil and Political Rights_) +- [3.1.2.] Hold any person in slavery, servitude, or forced labor (See Article 4, _United Nations Universal Declaration of Human Rights_; Article 8, _International Covenant on Civil and Political Rights_); +- [3.1.3.] Contribute to the institution of slavery, slave trading, forced labor, or unlawful child labor (See Article 4, _United Nations Universal Declaration of Human Rights_; Article 8, _International Covenant on Civil and Political Rights_); +- [3.1.4.] Torture or subject any person to cruel, inhumane, or degrading treatment or punishment (See Article 5, _United Nations Universal Declaration of Human Rights_; Article 7, _International Covenant on Civil and Political Rights_); +- [3.1.5.] Discriminate on the basis of sex, gender, sexual orientation, race, ethnicity, nationality, religion, caste, age, medical disability or impairment, and/or any other like circumstances (See Article 7, _United Nations Universal Declaration of Human Rights_; Article 2, _International Covenant on Economic, Social and Cultural Rights_; Article 26, _International Covenant on Civil and Political Rights_); +- [3.1.6.] Prevent any person from exercising his/her/their right to seek an effective remedy by a competent court or national tribunal (including domestic judicial systems, international courts, arbitration bodies, and other adjudicating bodies) for actions violating the fundamental rights granted to him/her/them by applicable constitutions, applicable laws, or by this License (See Article 8, _United Nations Universal Declaration of Human Rights_; Articles 9 and 14, _International Covenant on Civil and Political Rights_); +- [3.1.7.] Subject any person to arbitrary arrest, detention, or exile (See Article 9, _United Nations Universal Declaration of Human Rights_; Article 9, _International Covenant on Civil and Political Rights_); +- [3.1.8.] Subject any person to arbitrary interference with a person’s privacy, family, home, or correspondence without the express written consent of the person (See Article 12, _United Nations Universal Declaration of Human Rights_; Article 17, _International Covenant on Civil and Political Rights_); +- [3.1.9.] Arbitrarily deprive any person of his/her/their property (See Article 17, _United Nations Universal Declaration of Human Rights_); +- [3.1.10.] Forcibly remove indigenous peoples from their lands or territories or take any action with the aim or effect of dispossessing indigenous peoples from their lands, territories, or resources, including without limitation the intellectual property or traditional knowledge of indigenous peoples, without the free, prior, and informed consent of indigenous peoples concerned (See Articles 8 and 10, _United Nations Declaration on the Rights of Indigenous Peoples_); +- [3.1.11.] _Fossil Fuel Divestment_: Be an individual or entity, or a representative, agent, affiliate, successor, attorney, or assign of an individual or entity, on the [FFI Solutions Carbon Underground 200 list](https://www.ffisolutions.com/research-analytics-index-solutions/research-screening/the-carbon-underground-200/?cn-reloaded=1); +- [3.1.12.] _Ecocide_: Commit ecocide (see original for full definition); +- [3.1.13.] _Extractive Industries_: Be an individual or entity, or a representative, agent, affiliate, successor, attorney, or assign of an individual or entity, that engages in fossil fuel or mineral exploration, extraction, development, or sale; +- [3.1.14.] _Boycott / Divestment / Sanctions_: Be an individual or entity, or a representative, agent, affiliate, successor, attorney, or assign of an individual or entity, identified by the Boycott, Divestment, Sanctions (“BDS”) movement on its website ( and ) as a target for boycott; +- [3.1.15.] _Taliban_: Be an individual or entity that engages in any commercial transactions with the Taliban or is a representative, agent, affiliate, successor, attorney, or assign of the Taliban; +- [3.1.16.] _Myanmar_: Be an individual or entity that engages in any commercial transactions with the Myanmar/Burmese military junta or is a representative, agent, affiliate, successor, attorney, or assign of the Myanmar/Burmese government; +- [3.1.17.] _US Tariff Act_: Be an individual or entity which U.S. Customs and Border Protection (CBP) has currently issued a Withhold Release Order (WRO) or finding against based on reasonable suspicion of forced labor, or is a representative, agent, affiliate, successor, attorney, or assign of such an entity; +- [3.1.18.] _Mass Surveillance_: Be a government agency or multinational corporation, or a representative, agent, affiliate, successor, attorney, or assign of a government or multinational corporation, which participates in mass surveillance programs; +- [3.1.19.] _Military Activities_: Be an entity or a representative, agent, affiliate, successor, attorney, or assign of an entity which conducts military activities; +- [3.1.20.] _Law Enforcement_: Be an individual or entity, or a representative, agent, affiliate, successor, attorney, or assign of an individual or entity, that provides good or services to, or otherwise enters into any commercial contracts with, any local, state, or federal law enforcement agency; +- [3.1.21.] _Media_: Be an individual or entity, or a representative, agent, affiliate, successor, attorney, or assign of an individual or entity, that broadcasts messages promoting killing, torture, or other forms of extreme violence; +- [3.1.22.] Interfere with Workers' free exercise of the right to organize and associate (See Article 20, United Nations Universal Declaration of Human Rights; C087 - Freedom of Association and Protection of the Right to Organise Convention, 1948 (No. 87), International Labour Organization; Article 8, International Covenant on Economic, Social and Cultural Rights); +- [3.1.23.] Harm the environment in a manner inconsistent with local, state, national, or international law. + +#### [3.1.24.] **Artificial Intelligence (AI) and Dataset Prohibition:** +- The Licensee SHALL NOT use, copy, modify, reproduce, distribute, or prepare derivative works of the Software, in whole or in part, for the purpose of training, developing, operating, or deploying artificial intelligence (AI) or machine learning (ML) models, systems, or services, including but not limited to large language models, generative AI, or any automated decision-making systems. +- The Licensee SHALL NOT use, copy, reproduce, distribute, or otherwise process the Software, in whole or in part, as part of any dataset, corpus, or collection of data for the purpose of training, fine-tuning, evaluating, testing, benchmarking, or otherwise developing artificial intelligence (AI) or machine learning (ML) models, systems, or services. +- The Licensee SHALL NOT be an entity whose primary business is the development, deployment, or commercialization of AI or ML systems, or a representative, agent, affiliate, successor, attorney, or assign of such an entity. +- For the avoidance of doubt, any use, inclusion, reference, or incorporation of the Software, in whole or in part, in connection with the training, development, operation, evaluation, benchmarking, or deployment of any AI or ML model, system, or service is strictly prohibited, regardless of the materiality or intent of such use. +- The prohibitions of this section apply to any use of the Software in connection with, in support of, or as part of any process, workflow, or system involving AI or ML, whether or not the Software is directly incorporated into the AI/ML model or system. +- These prohibitions apply regardless of whether the use is for commercial, non-commercial, academic, research, or any other purpose. +- The prohibitions of this section apply to any use, in whole or in part, of the Software. +- For the purposes of this License, any output, result, or data generated by the Software, or derived from the Software, is subject to the same restrictions as the Software itself. +- These prohibitions apply to all uses of the Software, whether public, private, internal, or external, and regardless of whether the Software is distributed or made available to third parties. + +#### [3.1.25.] **No Data Mining, Scraping, or Automated Acquisition:** +- The Licensee SHALL NOT use any automated means, including but not limited to bots, scrapers, crawlers, or any current or future automated, semi-automated, or programmatic method, tool, or technology, whether known or unknown at the time of this License, to access, copy, download, or otherwise acquire the Software or any part thereof for any purpose, including but not limited to AI/ML training, dataset creation, or data analysis. + +#### [3.1.26.] **No Indirect Use or Circumvention:** +- The Licensee SHALL NOT use, or cause or permit others to use, the Software, in whole or in part, indirectly or through intermediaries, for any purpose prohibited by this License, including but not limited to inclusion in third-party datasets, corpora, or as part of any service or product that enables or facilitates AI/ML training or development. +- The Licensee SHALL take all reasonable and practical steps to ensure that any third party to whom the Software is provided, directly or indirectly, is made aware of and complies with the prohibitions of this License, including but not limited to the AI/ML, dataset, and data scraping prohibitions. The Licensee SHALL immediately cease distribution to, and take reasonable steps to prevent further use by, any third party found to be in violation of these prohibitions. + +#### [3.1.27.] **Unethical Megacorporations and User Data Harvesting:** +- The Licensee SHALL NOT be, or be owned or controlled by, a corporation or entity that: + - (a) has been found by a court of competent jurisdiction, regulatory body, or credible investigative reporting to systematically harvest, exploit, or monetize user data without meaningful informed consent, or + - (b) is widely recognized as engaging in unethical data practices, including but not limited to Google (Alphabet), Microsoft, Amazon, Meta (Facebook), or their subsidiaries, or + - (c) is a representative, agent, affiliate, successor, attorney, or assign of such an entity. +- The named entities are provided as examples only and do not limit the scope of this prohibition. Any entity engaging in similar practices, as determined by a court of competent jurisdiction, regulatory body, or credible investigative reporting, is also covered. + +#### [3.1.28.] **Platforms that Underpay Creators or Contributors:** +- The Licensee SHALL NOT be, or be owned or controlled by, a platform or service that: + - (a) derives significant revenue from the creative or productive work of individuals (such as musicians, artists, writers, or gig workers), and + - (b) has been credibly accused, through legal action, regulatory finding, or substantial evidence, of systematically underpaying, exploiting, or failing to fairly compensate those individuals for their contributions, including but not limited to Spotify, or + - (c) is a representative, agent, affiliate, successor, attorney, or assign of such an entity. +- The named entities are provided as examples only and do not limit the scope of this prohibition. Any entity engaging in similar practices, as determined by a court of competent jurisdiction, regulatory body, or credible investigative reporting, is also covered. + +--- + +### [3.2.] The Licensee SHALL: + +- [3.2.1.] _Social Auditing_: Only use social auditing mechanisms that adhere to Worker-Driven Social Responsibility Network’s Statement of Principles () over traditional social auditing mechanisms, to the extent the Licensee uses any social auditing mechanisms at all; +- [3.2.2.] _Workers on Board of Directors_: Ensure that if the Licensee has a Board of Directors, 30% of Licensee’s board seats are held by Workers paid no more than 200% of the compensation of the lowest paid Worker of the Licensee; +- [3.2.3.] _Supply Chain_: Provide clear, accessible supply chain data to the public in accordance with the following conditions: + - [3.2.3.1.] All data will be on Licensee’s website and/or, to the extent Licensee is a representative, agent, affiliate, successor, attorney, subsidiary, or assign, on Licensee’s principal’s or parent’s website or some other online platform accessible to the public via an internet search on a common internet search engine; and + - [3.2.3.2.] Data published will include, where applicable, manufacturers, top tier suppliers, subcontractors, cooperatives, component parts producers, and farms; +- [3.2.4.] Provide equal pay for equal work where the performance of such work requires equal skill, effort, and responsibility, and which are performed under similar working conditions, except where such payment is made pursuant to: + - [3.2.4.1.] A seniority system; + - [3.2.4.2.] A merit system; + - [3.2.4.3.] A system which measures earnings by quantity or quality of production; or + - [3.2.4.4.] A differential based on any other factor other than sex, gender, sexual orientation, race, ethnicity, nationality, religion, caste, age, medical disability or impairment, and/or any other like circumstances (See 29 U.S.C.A. § 206(d)(1); Article 23, _United Nations Universal Declaration of Human Rights_; Article 7, _International Covenant on Economic, Social and Cultural Rights_; Article 26, _International Covenant on Civil and Political Rights_); +- [3.2.5.] Allow for reasonable limitation of working hours and periodic holidays with pay (See Article 24, _United Nations Universal Declaration of Human Rights_; Article 7, _International Covenant on Economic, Social and Cultural Rights_). + +--- + +### [3.3.] **Audit and Transparency Rights:** +- The Licensor reserves the right to request, and the Licensee agrees to provide within 30 days, reasonable documentation or evidence demonstrating compliance with all terms of this License, including but not limited to the prohibition on AI/ML use, dataset creation, and data scraping. Failure to provide requested documentation or evidence of compliance within 30 days shall constitute a material breach of this License and result in immediate termination of all rights granted hereunder. + +### [3.4.] **Attribution and Notice Requirements:** +- Any copy, distribution, or derivative of the Software must include this License and a prominent notice stating: + _“Use of this software for AI/ML training, dataset creation, or automated data acquisition is strictly prohibited.”_ +- Licensee must ensure that the License and all required notices are provided in a clear, conspicuous, and accessible manner at every point of distribution, download, or access, including but not limited to websites, repositories, and physical media. + +### [3.5.] **Statutory Damages / Penalty Clause:** +- Any violation of the AI/ML prohibition, dataset prohibition, or data scraping prohibition in this License shall entitle the Licensor to seek statutory damages of up to $150,000 per violation, or the maximum allowed by applicable law, in addition to any other remedies available at law or in equity. Statutory damages are in addition to, and not in lieu of, any actual damages, injunctive relief, or other remedies available at law or in equity. + +### [3.6.] **Retroactive Termination:** +- Any violation of the terms of this License, including but not limited to the AI/ML prohibition, dataset prohibition, or data scraping prohibition, shall result in the immediate and retroactive termination of all rights granted under this License. + +### [3.7.] **Third-Party Beneficiary Clause:** +- All contributors to the Software and any Supply Chain Impacted Party are intended third-party beneficiaries of this License and shall have the right to enforce its terms. + +--- + +## [4.] SUPPLY CHAIN IMPACTED PARTIES + +_This section identifies additional individuals or entities that a Licensee could harm as a result of violating the Ethical Standards section, the condition that the Licensee must voluntarily accept a Duty of Care for those individuals or entities, and the right to a private right of action that those individuals or entities possess as a result of violations of the Ethical Standards section._ + +- **[4.1.]** In addition to the above Ethical Standards, Licensee voluntarily accepts a Duty of Care for Supply Chain Impacted Parties of this License, including individuals and communities impacted by violations of the Ethical Standards. The Duty of Care is breached when a provision within the Ethical Standards section is violated by a Licensee, one of its successors or assigns, or by an individual or entity that exists within the Supply Chain prior to a good or service reaching the Licensee. + +- **[4.2.]** Breaches of the Duty of Care, as stated within this section, shall create a private right of action, allowing any Supply Chain Impacted Party harmed by the Licensee to take legal action against the Licensee in accordance with applicable negligence laws, whether they be in tort law, delict law, and/or similar bodies of law closely related to tort and/or delict law, regardless if Licensee is directly responsible for the harms suffered by a Supply Chain Impacted Party. Nothing in this section shall be interpreted to include acts committed by individuals outside of the scope of his/her/their employment. + +--- + +## [5.] NOTICE + +_This section explains when a Licensee must notify others of the License._ + +- **[5.1.] Distribution of Notice:** + Licensee must ensure that everyone who receives a copy of or uses any part of Software from Licensee, with or without changes, also receives the License and the copyright notice included with Software (and if included by the Licensor, patent, trademark, and attribution notice). Licensee must ensure that License is prominently displayed so that any individual or entity seeking to download, copy, use, or otherwise receive any part of Software from Licensee is notified of this License and its terms and conditions. Licensee must cause any modified versions of the Software to carry prominent notices stating that Licensee changed the Software. Licensee must ensure that the License and all required notices are provided in a clear, conspicuous, and accessible manner at every point of distribution, download, or access, including but not limited to websites, repositories, and physical media. + +- **[5.2.] Modified Software:** + Licensee is free to create modifications of the Software and distribute only the modified portion created by Licensee, however, any derivative work stemming from the Software or its code must be distributed pursuant to this License, including this Notice provision. + +- **[5.3.] Recipients as Licensees:** + Any individual or entity that uses, copies, modifies, reproduces, distributes, or prepares derivative work based upon the Software, all or part of the Software’s code, or a derivative work developed by using the Software, including a portion of its code, is a Licensee as defined above and is subject to the terms and conditions of this License. + +--- + +## [6.] REPRESENTATIONS AND WARRANTIES + +- **[6.1.] Disclaimer of Warranty:** + TO THE FULL EXTENT ALLOWED BY LAW, THIS SOFTWARE COMES “AS IS,” WITHOUT ANY WARRANTY, EXPRESS OR IMPLIED, AND LICENSOR SHALL NOT BE LIABLE TO ANY PERSON OR ENTITY FOR ANY DAMAGES OR OTHER LIABILITY ARISING FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR THIS LICENSE, UNDER ANY LEGAL CLAIM. + +- **[6.2.] Limitation of Liability:** + LICENSEE SHALL HOLD LICENSOR HARMLESS AGAINST ANY AND ALL CLAIMS, DEBTS, DUES, LIABILITIES, LIENS, CAUSES OF ACTION, DEMANDS, OBLIGATIONS, DISPUTES, DAMAGES, LOSSES, EXPENSES, ATTORNEYS' FEES, COSTS, LIABILITIES, AND ALL OTHER CLAIMS OF EVERY KIND AND NATURE WHATSOEVER, WHETHER KNOWN OR UNKNOWN, ANTICIPATED OR UNANTICIPATED, FORESEEN OR UNFORESEEN, ACCRUED OR UNACCRUED, DISCLOSED OR UNDISCLOSED, ARISING OUT OF OR RELATING TO LICENSEE’S USE OF THE SOFTWARE. NOTHING IN THIS SECTION SHOULD BE INTERPRETED TO REQUIRE LICENSEE TO INDEMNIFY LICENSOR, NOR REQUIRE LICENSOR TO INDEMNIFY LICENSEE. + +--- + +## [7.] TERMINATION + +- **[7.1.] Violations of Ethical Standards or Breaching Duty of Care:** + If Licensee violates the Ethical Standards section or Licensee, or any other person or entity within the Supply Chain prior to a good or service reaching the Licensee, breaches its Duty of Care to Supply Chain Impacted Parties, Licensee must remedy the violation or harm caused by Licensee within 30 days of being notified of the violation or harm. If Licensee fails to remedy the violation or harm within 30 days, all rights in the Software granted to Licensee by License will be null and void as between Licensor and Licensee. + +- **[7.2.] Failure of Notice:** + If any person or entity notifies Licensee in writing that Licensee has not complied with the Notice section of this License, Licensee can keep this License by taking all practical steps to comply within 30 days after the notice of noncompliance. If Licensee does not do so, Licensee’s License (and all rights licensed hereunder) will end immediately. + +- **[7.3.] Judicial Findings:** + In the event Licensee is found by a civil, criminal, administrative, or other court of competent jurisdiction, or some other adjudicating body with legal authority, to have committed actions which are in violation of the Ethical Standards or Supply Chain Impacted Party sections of this License, all rights granted to Licensee by this License will terminate immediately. + +- **[7.4.] Patent Litigation:** + If Licensee institutes patent litigation against any entity (including a cross-claim or counterclaim in a suit) alleging that the Software, all or part of the Software’s code, or a derivative work developed using the Software, including a portion of its code, constitutes direct or contributory patent infringement, then any patent license, along with all other rights, granted to Licensee under this License will terminate as of the date such litigation is filed. + +- **[7.5.] Additional Remedies:** + Termination of the License by failing to remedy harms in no way prevents Licensor or Supply Chain Impacted Party from seeking appropriate remedies at law or in equity. + +--- + +## [8.] MISCELLANEOUS + +- **[8.1.] Conditions:** + Sections 3, 4.1, 5.1, 5.2, 7.1, 7.2, 7.3, and 7.4 are conditions of the rights granted to Licensee in the License. + +- **[8.2.] Equitable Relief:** + Licensor and any Supply Chain Impacted Party shall be entitled to equitable relief, including injunctive relief or specific performance of the terms hereof, in addition to any other remedy to which they are entitled at law or in equity. + +- **[8.3.] Copyleft:** + All modified software, source code, or other derivative work must be licensed exclusively under the exact same conditions as this License, and may not be dual-licensed or sublicensed under any other terms. + +- **[8.4.] Severability:** + If any term or provision of this License is determined to be invalid, illegal, or unenforceable by a court of competent jurisdiction, any such determination of invalidity, illegality, or unenforceability shall not affect any other term or provision of this License or invalidate or render unenforceable such term or provision in any other jurisdiction. If the determination of invalidity, illegality, or unenforceability by a court of competent jurisdiction pertains to the terms or provisions contained in the Ethical Standards section of this License, all rights in the Software granted to Licensee shall be deemed null and void as between Licensor and Licensee. + +- **[8.5.] Section Titles:** + Section titles are solely written for organizational purposes and should not be used to interpret the language within each section. + +- **[8.6.] Citations:** + Citations are solely written to provide context for the source of the provisions in the Ethical Standards. + +- **[8.7.] Section Summaries:** + Some sections have a brief _italicized description_ which is provided for the sole purpose of briefly describing the section and should not be used to interpret the terms of the License. + +- **[8.8.] Entire License:** + This is the entire License between the Licensor and Licensee with respect to the claims released herein and that the consideration stated herein is the only consideration or compensation to be paid or exchanged between them for this License. This License cannot be modified or amended except in a writing signed by Licensor and Licensee. + +- **[8.9.] Successors and Assigns:** + This License shall be binding upon and inure to the benefit of the Licensor’s and Licensee’s respective heirs, successors, and assigns. Any transfer or assignment of rights under this License is void unless the transferee or assignee agrees in writing to be bound by all terms and conditions of this License. + +- **[8.10.] Jurisdiction and Venue:** + Any dispute arising under or in connection with this License shall be resolved exclusively in the courts of **Romania**, and the parties consent to the personal jurisdiction and venue of such courts. In addition to the exclusive jurisdiction of the courts of Romania, the Licensor and Licensee agree that any judgment or order issued by such courts may be enforced in any jurisdiction in which the Licensee operates or has assets. Alternatively, at the Licensor’s sole discretion, any dispute may be resolved by binding arbitration under the rules of the International Chamber of Commerce. + +- **[8.11.] No Waiver of Rights:** + Failure by the Licensor to enforce any provision of this License shall not constitute a waiver of the Licensor’s rights to enforce such provision or any other provision of this License. No waiver of any provision of this License shall be effective unless in writing and signed by the Licensor. \ No newline at end of file diff --git a/self-hosted-database.md b/self-hosted-database.md index 8ca0c77..10d6b3d 100644 --- a/self-hosted-database.md +++ b/self-hosted-database.md @@ -1,99 +1,171 @@ -This guide will show you how to setup the necessary stuff to be able to use your own authentication system and database for accounts. please do note that you will have to enter the same configurations for each device. +# Self-Hosted Database Setup Guide -**This Guide Assumes You're Doing everything On Your Local Machine. This is still fully possible on a VPS Though.** +This guide will show you how to set up your own authentication system and database for Monochrome accounts. -### Required: +> ⚠️ **Note:** You will need to enter the same configurations on each device where you want to use your custom database. -- A Computer (this computer will be the one hosting the database) -- Firebase Account (Only Used For Authentication) -- [PocketBase](https://pocketbase.io) (App we use to manage The Database, Install This on the computer you want to host the database on) -- Domain (you can get one for free at [DigitalPlat](https://domain.digitalplat.org/)) +--- -### Step 1: Setup Firebase Authentication +## Table of Contents -Go to the [Firebase Console](https://console.firebase.google.com) and create a new project. then, on the left sidebar, click the **Build** section and select **Authentication**. +- [Prerequisites](#prerequisites) +- [Step 1: Setup Firebase Authentication](#step-1-setup-firebase-authentication) +- [Step 2: PocketBase Setup](#step-2-pocketbase-setup) +- [Step 3: Cloudflare Tunnel Setup](#step-3-cloudflare-tunnel-setup) +- [Step 4: Getting Configurations](#step-4-getting-configurations) +- [Step 5: Linking with Monochrome](#step-5-linking-with-monochrome) +- [Troubleshooting](#troubleshooting) -1. Click **Get Started**. -2. Go to the **Sign-in method** tab. -3. Select **Google** And **Email** and enable it. -4. Set your project support email and click **Save**. +--- -### Step 1.1: Authorize The Domain +## Prerequisites -firebase by default makes you add trusted domains to connect to firebases authentication system, if your domain isnt on there, it wont allow you to login or signup. +Before starting, ensure you have: -1. In the **Authentication** section, go to the **Settings** tab. -2. Click **Authorized domains** in the left sub-menu. -3. Click **Add domain**. -4. Add your hosting domain (if you're still using the normal monochrome site, just add `monochrome.samidy.com`, or whatever mirror you like to use (eg. `monochrome.tf`). otherwise, if you're self hosting the website too, add your hosted domain). - - _Note: `localhost` is usually added by default for local testing. you likely wont have people abusing your system, so you can leave this in by default._ +- A computer to host the database (can also use a VPS) +- A [Firebase](https://firebase.google.com) account (for authentication only) +- [PocketBase](https://pocketbase.io) installed on your host machine +- A domain name (free options available at [DigitalPlat](https://domain.digitalplat.org/)) -### Step 2: PocketBase Setup +> 💡 **This guide assumes you're setting everything up on your local machine. The process is identical for a VPS.** -1. download [PocketBase](https://pocketbase.io) and follow their setup guide. -2. make 2 collections: `DB_users` and `public_playlists`. do NOT use the normal "users" collection. -3. Add these fields to `DB_users`: +--- -- name: `firebase_id` type: `Plain Text` -- name: `lastUpdated` type: `Number` -- name: `history` type: `JSON` -- name: `library` type: `JSON` -- name: `user_playlists` type: `JSON` -- name: `user_folders` type: `JSON` -- name: `deleted_playlists` type: `JSON` +## Step 1: Setup Firebase Authentication -4. Add these fields to `public_playlists`: +### 1.1 Create a Firebase Project -- name: `firebase_id` type: `Plain Text` -- name: `addedAt` type: `Number` -- name: `numberOfTracks` type: `Number` -- name: `OriginalId` type: `Plain Text` -- name: `publishedAt` type: `Number` -- name: `title` type: `Plain Text` -- name: `uid` type: `Plain Text` -- name: `uuid` type: `Plain Text` -- name: `tracks` type: `JSON` -- name: `image` type: `URL` +1. Go to the [Firebase Console](https://console.firebase.google.com) +2. Create a new project +3. On the left sidebar, click **Build** → **Authentication** +4. Click **Get Started** -5. edit the `API Rules` for both `DB_users` and `public_playlists` to these: +### 1.2 Enable Sign-in Methods -#### `DB_users` +1. Go to the **Sign-in method** tab +2. Enable **Google** and **Email** providers +3. Set your project support email +4. Click **Save** -![DB_users](https://i.ibb.co/WvFgJvFJ/image.png) +### 1.3 Authorize Your Domain -#### `public_playlists` +Firebase requires authorized domains for authentication: -![public_playlists](https://i.ibb.co/WpW7F3kk/image.png) +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 -Now that you have setup collections, rules and fields, we can now work on putting them out on the internet. +> 💡 `localhost` is usually added by default for local testing. You can leave this enabled. -### Step 3: Cloudflared +--- -while you can use the usual `127.0.0.1` link pocketbase gives you, this is a local domain and you cant enter it on any other device, so it would practically be useless. to open this up, while we can port forward, this could be dangerous and attackers could use that as a vulnerability. to securely set this up, we are going to be using cloudflared. +## Step 2: PocketBase Setup -1. Make an account at the [Cloudflare Dashboard](https://dash.cloudflare.com). -2. In the Left Sidebar, Click "Zero Trust". -3. Set Up Zero Trust, then in the left sidebar, Click "Networks" Then "connectors". -4. Select "Cloudflared". -5. Give Your Tunnel A Name (eg. `My very cool monochrome database wow im so cool`) -6. then, you will get a guide on how to install cloudflared and set it up for your machine. -7. You will get a window to setup hostnames, Note that you will require a valid domain as cloudflare doesnt allow `pages.dev` domains. you can get one for free at [DigitalPlat](https://domain.digitalplat.org/), but we will not show you how to set it up and how to connect it to cloudflare. -8. at the "Service" section for the setup hostnames window, select "HTTP" and input the URL for pocketbase (eg. `127.0.0.1:8090`). - after this, your database will be available at the chosen domain. +### 2.1 Install and Configure -### Step 4: Getting Configurations +1. Download [PocketBase](https://pocketbase.io) and follow their setup guide +2. Access the PocketBase Admin UI (typically at `http://127.0.0.1:8090/_/`) -You are almost done, now you just need to get configurations so you can add them to monochrome. +### 2.2 Create Collections -first, get your authentication config: +Create two collections: `DB_users` and `public_playlists` (do NOT use the default "users" collection) -1. Open Firebase Console and click on your project. -2. click the Gear Icon (⚙️) next to "Project Overview" and select **Project settings**. -3. In the **General** tab, scroll down to "Your apps" and click the **Web icon (``)**. -4. Register the app (e.g., "Monochrome Auth"). -5. You will see a `firebaseConfig` object. It looks like this: +#### 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: `@request.auth.id != ""` +- View Rule: `@request.auth.id != ""` +- Create Rule: `@request.auth.id != ""` +- Update Rule: `@request.auth.id != ""` +- Delete Rule: `@request.auth.id != ""` + +**public_playlists API Rules:** + +- List/Search Rule: `true` +- View Rule: `true` +- Create Rule: `@request.auth.id != ""` +- Update Rule: `@request.auth.id != ""` +- Delete Rule: `@request.auth.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](https://dash.cloudflare.com) +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](https://domain.digitalplat.org/). + +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](https://console.firebase.google.com), 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: + +```javascript const firebaseConfig = { apiKey: 'AIzaSy...', authDomain: 'your-project.firebaseapp.com', @@ -105,19 +177,64 @@ const firebaseConfig = { }; ``` -6. **Copy only the part with the curly braces `{ ... }`**. +> ⚠️ **Copy only the object content inside the curly braces `{ ... }`** -For The Database: -just copy the link for your database. +### 4.2 Get Database URL -### Step 5: Linking with monochrome +Simply copy your PocketBase domain from Cloudflare (e.g., `https://db.yourdomain.com`) -now all you need to do is add your configurations in monochrome. +--- -1. Go to settings in monochrome. -2. Click "ADVANCED: Custom Account Database" -3. in the database Config input window, input your database link. -4. in the authentication config input window, input the JSON object you got from firebase. -5. Click "Save" +## Step 5: Linking with Monochrome -Thats it! you now have setup a custom authentication system and database system. do note, on every device you wanna use your custom database on, you will have to repeat step 5 on the given device. +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](https://discord.gg/monochrome) (if available) +- Open an issue on [GitHub](https://github.com/SamidyFR/monochrome/issues) +- Check existing [GitHub issues](https://github.com/SamidyFR/monochrome/issues) for solutions