Serendipity

The ability to find valuable or agreeable things not sought for.

— Merriam-Webster

This is a music recommendation app without algorithm. We want you to get pure random songs while allowing for simple and effective filtering.

We use the Discogs API as the data backbone for songs, and all the streaming is done via Youtube. Start listening and get ready to be surprised!

Installation

Requirements:

• Docker + Docker Compose
• Make (optional, for shortcuts)

Clone the repo and prepare the setup:

cp .env.example .env
# edit .env if needed

Bring up the stack:

make up
# or: docker compose up -d

Run the database migrations:

make db_migrate

The app will be available at http://localhost:4000 (or the SERVER_PORT you set).

Setup

Environment variables live in .env:

• SERVER_PORT - port for the web server (default 4000)
• DB_DSN - Postgres connection string used by the app
• POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB - database settings for the container

Usage

Common commands (via make):

• make up - start services
• make down - stop services
• make rebuild - rebuild and start services
• make logs - follow all logs
• make logs_web - follow web logs
• make logs_db - follow database logs
• make web_connect - shell into the web container
• make db_connect - open psql in the database container
• make db_migrate - run migrations
• make db_rollback - rollback last migration

Direct Docker Compose equivalents also work, for example: docker compose up -d.

Architecture

For a brief overview of the system design and diagrams, see docs/architecture.md and the rest of the docs folder.