Mirlo

A RESTful API and client.

Main libraries:

• Express
• Prisma Client

Contributing

Download and install

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.

For the API:

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.

For the client:

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

You can log in with these credentials:

admin@admin.example
test1234

Email

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

Background Jobs

Making changes to background jobs.

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

Workers (Uploading Music, Images, Etc)

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

Running migrations

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

Stripe

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-connect-to localhost:3000/v1/webhooks/stripe/connect

All of Mirlo's payment activity happens on connected Stripe accounts, so it's the Connect webhook events that matter. This forwards them to your localhost:3000. It'll also spit out a signing secret — set it as STRIPE_WEBHOOK_CONNECT_SIGNING_SECRET in the .env file.

Then to trigger a specific workflow (note that stripe trigger fires events on your platform account by default — pass --stripe-account with a connected account id so the event reaches the Connect endpoint):

# this is what's needed to store a subscription
stripe trigger checkout.session.completed --stripe-account acct_yourconnectedaccount --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.

CRON Jobs

Some cron jobs exist:

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

File Storage

See the file storage docs for details.

Database

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

Tests

See the test/README.md instructions.

Apple Chip Errors w/ Docker

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

Docker connectivity issues.

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"
  ],

Credits

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