Quick Start

The simplest, safest way to run Immerle: Docker Compose, with Postgres instead of SQLite.

Not a sysadmin? Read this

If you don't already know why "don't forward ports on your router" matters, follow this section as-is and don't deviate: every step is chosen to be the thing that's hardest to get wrong, not the thing with the most options. The Installation and Configuration pages cover the other ways to run Immerle (SQLite, building from source, running behind your own reverse proxy…) once you want more control.

Run it

Create a folder, drop your music under music/, and save this as docker-compose.yml next to it. Music, the database and daily Postgres backups each live in their own Docker volume rather than a host folder, more portable if you manage this stack from Portainer, Komodo or similar. The admin password below is generated fresh right now, reload this page for a different one:

docker-compose.yml

services:
  immerle:
    image: ghcr.io/immerle/immerle:latest
    ports:
      - "4533:4533"
    environment:
      DATABASE_DRIVER: "postgres"
      DATABASE_DSN: "postgres://immerle:immerle@postgres:5432/immerle?sslmode=disable"
      LIBRARY_DATA_DIR: "/data"
      LIBRARY_PATHS: "/music"
      ADMIN_USERNAME: "admin"
      ADMIN_PASSWORD: "change-me"
    volumes:
      - immerle-music:/music:ro
      - immerle-data:/data
    depends_on:
      postgres:
        condition: service_healthy
    restart: unless-stopped

  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: immerle
      POSTGRES_PASSWORD: immerle
      POSTGRES_DB: immerle
    volumes:
      - immerle-pg:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U immerle"]
      interval: 5s
      timeout: 3s
      retries: 5
    restart: unless-stopped

  # Daily pg_dump, keeps the last 7 and prunes anything older.
  backup:
    image: prodrigestivill/postgres-backup-local:16
    depends_on:
      postgres:
        condition: service_healthy
    environment:
      POSTGRES_HOST: postgres
      POSTGRES_DB: immerle
      POSTGRES_USER: immerle
      POSTGRES_PASSWORD: immerle
      SCHEDULE: "@daily"
      BACKUP_KEEP_DAYS: 7
      BACKUP_KEEP_WEEKS: 0
      BACKUP_KEEP_MONTHS: 0
    volumes:
      - immerle_backup:/backups
    restart: unless-stopped

volumes:
  immerle-data:
  immerle-pg:
  immerle-music:
  immerle_backup:

Start it, then copy your music into the immerle-music volume:

docker compose up -d
docker run --rm -v immerle-music:/dest -v "$PWD/music":/src:ro alpine cp -a /src/. /dest/

Open http://localhost:4533 on the same machine and sign in with admin / the password from the ADMIN_PASSWORD line above. That's it: the server, database and your library are all up, with the last 7 daily database backups always kept in the immerle_backup volume.

Next

• Choosing a client: connect and pick between the Immerle app, iml, or a Subsonic client.