Monochrome

Monochrome uses PocketBase as its server-side datastore for managing account data, including profiles, library entries, history, playlists, folders, favorite albums, and themes.

To set up the database, import the provided pb_schema.json file into a fresh PocketBase instance. This file contains the complete collection schema required for Monochrome to function.

Docker Compose automatically merges docker-compose.override.yml into docker-compose.yml if it exists in the same directory. This is the recommended way for forks to add custom services (e.g., Traefik, monitoring) or modify existing services (e.g., adding labels or networks) without changing the upstream docker-compose.yml.

# Example: Adding Traefik labels to PocketBase in your fork
services:
    pocketbase:
        labels:
            - traefik.enable=true
            - traefik.http.routers.pocketbase.rule=Host(`pocketbase.example.com`)
            - traefik.http.routers.pocketbase.entrypoints=websecure
            - traefik.http.routers.pocketbase.tls.certresolver=letsencrypt
            - traefik.http.services.pocketbase.loadbalancer.server.port=8090
        networks:
            - proxy-network

networks:
    proxy-network:
        external: true

Monochrome themes are CSS snippets that override default CSS variables (custom properties). To create a theme, define your desired colors and styles inside a :root block.

:root {
    /* Base Colors */
    --background: #0a0a0a;
    --foreground: #ededed;

    /* UI Elements */
    --card: #1a1a1a;
    --card-foreground: #ededed;
    --border: #2a2a2a;

    /* Accents */
    --primary: #3b82f6;
    --primary-foreground: #ffffff;
    --secondary: #2a2a2a;
    --secondary-foreground: #ededed;

    /* Text */
    --muted: #2a2a2a;
    --muted-foreground: #a0a0a0;

    /* Special */
    --highlight: #3b82f6;
    --ring: #3b82f6;
    --radius: 8px;
    --font-family: 'Inter', sans-serif;
}

To share your theme with the community:

1. Name & Description: Provide a unique name and a brief description.
2. Author Website: (Optional) Provide a link to your website. If you have a Monochrome profile, your name will automatically link to it.
3. Submit: Click "Upload Theme".

Monochrome uses Docker Compose profiles to control which services are started. Services without a profile always run. Services with a profile only run when that profile is explicitly activated.

You can deploy Monochrome using Docker Compose. Choose the command based on your intended environment:

Monochrome Only (Production-like)

Runs the standard Monochrome service.

Development

Runs the Monochrome service with the dev profile enabled, which provides hot-reloading. Note that this requires source code to be present on the host machine.

Visit http://localhost:3000 for Monochrome Only or http://localhost:5173 for Development.

# Monochrome Only
docker compose up -d

# Development
docker compose --profile dev up -d

To contribute a new instance to the official list, follow these steps:

1. Ensure your instance is stable and publicly accessible.
2. Open a pull request with the following details:
   • Instance URL
   • Provider name
   • Type (UI, API, or Both)
   • Brief description

To run Monochrome manually, ensure you have Bun (preferred) or Node.js (v20+ or v22+) and Git installed. Follow these steps to set up your development environment:

1. Clone the repository.
2. Install dependencies using bun install or npm install.
3. Start the development server using bun run dev or npm run dev.
4. Access the app at http://localhost:5173/.

git clone https://github.com/monochrome-music/monochrome.git
cd monochrome
bun install
bun run dev

The recommended way to self-host Monochrome is using Docker Compose. Note that accounts will not work on self-hosted instances because the Appwrite authentication system is restricted to authorized domains.

git clone https://github.com/monochrome-music/monochrome.git
cd monochrome/docker
docker compose up -d

By default, the app uses Vite preview, which restricts access to localhost. To allow access over Tailscale, you must modify vite.config.js to enable the host and allow your specific Tailscale hostname.

// In vite.config.js
preview: {
    host: true,
    allowedHosts: ['<your_tailscale_hostname>'], // e.g. pi5.tailf5f622.ts.net
},

Monochrome provides several official web interfaces (instances) to access the application. Use the primary instance for standard usage, or the mirrors if the primary is unavailable.

Official Instances:

• https://monochrome.tf (Primary)
• https://monochrome.samidy.com (Secondary mirror)
• https://lossless.wtf (Failover mirror)
• https://if-it-runs-ship-it.lol/ (Failover mirror)