Getting Started

Magritte is an application server designed to run on desktop-class machines, single-board computers, network-attached storage devices, and in the cloud.

Quick Start

Docker

Magritte is available as a Docker image published to the GitHub container registry. Use a docker compose file to customize the image to suit your use case:

services:
  magritte:
    image: ghcr.io/magritte-project/magritte:latest
    container_name: magritte
    restart: unless-stopped
    ports:
      - "8090:8090"
    volumes:
      # Database, generated secrets ($DATA_HOME/env), and other instance data
      - /path/to/data:/data
      # Your music library. Drop ":ro" if you enable uploads.
      - /path/to/your/music:/music:ro
    environment:
      # Public URL of this instance; used in links and the email sender address.
      WEB_URL: https://music.example.com

The containerized version of Magritte stores its data at /data and looks for music files at /music. Your docker compose file should specify volume rules for both of these paths.

The first time containerized Magritte is started, it will generate token secrets and salt and save them to a file in its data directory.

Important: By default, Magritte is started from its own user with UID/GID 1000 inside the container. You may need to give access to your data / music directories from the host system in order for Magritte to function. Alternatively, you can run the container as your host user:

services:
  magritte:
    ...
    user: "${UID:-1000}:${GID:-1000}"

If your host does not set $UID or $GID, like Synology Container Manager, you will need to acquire your UID and GID manually over SSH with the id command.

Python

Magritte is distributed as a Python package on PyPi. You can use pip (or any other Python package manager) to install it:

Optional extras

Desktop environment support Mailtrap email delivery

pip install magritte

pip install "magritte[mailtrap]"

pip install "magritte[desktop]"

pip install "magritte[desktop,mailtrap]"

When running Magritte outside of a desktop environment, you will need to generate secrets for it to sign tokens and manage passwords. Magritte can create these secrets for you:

python -m magritte generate-secrets >$HOME/.magritte/env

Once you’ve installed Magritte, you can run it with a python command:

$ magritte

This starts the server on port 8090. After a few moments, you should be able to navigate to the Magritte in your browser:

http://localhost:8090/

Development

Magritte is in rapid development. To get the latest features, you can run it from its development environment. Before you get started, make sure you have git and asdf installed on your machine. Follow the instructions on those projects’ pages to get set up.

With git and asdf installed, clone the GitHub project on your machine:

$ git clone git@github.com:magritte-project/magritte.git

You can then cd into magritte/ use the included bootstrap script to set up a local development environment:

$ ./bootstrap

Note: Magritte currently does not support development on Windows. Pull requests are welcome!

Once bootstrapping finishes, you can run the development API and web servers:

$ just dev

This starts the API server on port 6477 and the web front end on port 6479. After a few moments, you should be able to navigate to the Magritte web front end in your browser:

http://localhost:6479/