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.

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-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.

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