A RESTful API and client.

Main libraries:

• Express
• Prisma Client

Prerequisites:

• Docker
• Node.js 22
• Yarn 4

Once node is installed, you can use Corepack to automatically install the correct version of yarn (as defined in package.json):

corepack enable

If you'd like to use Nix, we have a basic shell.nix that includes Node.js, Yarn, and other tools to develop the client. Activate the shell using nix-shell at the top-level of the repository.

git clone https://github.com/funmusicplace/mirlo
cd mirlo
cp .env.example .env
docker compose watch # launches the server.
docker exec -it blackbird-api yarn prisma:seed # Seeds data for development

Go to localhost:3000/docs and see the Swagger API docs.

cp client/.env.example client/.env
yarn install
yarn client:start

You can log in with these credentials:

admin@admin.example
test1234

On production email gets sent by sendgrid or mailgun. To see e-mails during development, navigate to http://localhost:8025 to view all emails. Emails will appear in real-time as they're sent through the queue.

If during development you want to send actual emails (e.g. while testing an email provider), configure that provider on your Mirlo instance via the localhost admin UI, and set environment variable:

SEND_EMAILS_IN_DEV=true

Changes in background jobs aren't detected. You'll need to restart the docker container for them:

docker compose up -d --force-recreate --no-deps background

If you want to upload music or upload images, you'll need a worker running.

docker exec -it blackbird-api yarn ts-node src/jobs/queue-worker.ts run

NOTE: this is done automatically by the blackbird-background container in docker.

NOTE: In local development you can see the worker queue at /admin/queues on the server

Migrations will run automatically on docker-compose up. To make changes to the database, change the schema.prisma file and then run:

yarn prisma:migrate

Note: if this is your first time doing this you'll need to add a .env file to your /prisma folder. You can copy the .env.example and set the values correctly.

If your typescript for prisma is ever out of date, you can re-generate it with:

yarn prisma:build

By default Mirlo uses Stripe as its payment processor.

NOTE: Every 90 days you'll have to re-log-in to the stripe CLI with stripe login

To test webhooks, you'll have to run this:

stripe listen --forward-to localhost:3000/v1/webhooks/stripe

This will forward all stripe webhooks to your localhost:3000, and send them to the checkout/webhook URL. It'll also spit out a STRIPE_WEBHOOK_SIGNING_SECRET. You'll need to set that in the .env file.

Then to trigger a specific workflow:

# this is what's needed to store a subscription
stripe trigger checkout.session.completed --add checkout_session:metadata.userId=3 --add checkout_session:metadata.tierId=2

You'll also want fake Stripe data. You can find the details on that here.

Some cron jobs exist:

docker exec -it blackbird-api yarn ts-node src/jobs/every-minute-tasks.ts

See the file storage docs for details.

If you want to do logging in the database, you need to uncomment the log line in the prisma/prisma.ts file.

See the test/README.md instructions.

If you get errors when running the backbird-api and blackbird-background service like Error relocating /usr/lib/libgcc_s.so.1: unsupported relocation type 7, you'll need to follow these steps.

1. In terminal run softwareupdate --install-rosetta
2. In Docker Desktop, go to Settings -> General and ensure Use Rosetta for x86/amd64 emulation on Apple Silicon is checked.
3. Delete any previously created images
4. Run DOCKER_DEFAULT_PLATFORM=linux/amd64 docker compose up

It might be that your docker container can't reach yarn or github. As described here: either in Docker Desktop, edit the Docker Engine file to show the DNS, or edit /etc/docker/daemon.json directly:

"dns": [
    "10.0.0.2",
    "8.8.8.8"
  ],

A lot of the code here was originally written for the Resonate API and UI