Install crossonic-server

The recommended installation method for crossonic-server is Docker. The example commands in this guide assume you are using Linux.

Create Docker containers

To get started create a directory for crossonic-server:

mkdir ~/crossonic-server
cd ~/crossonic-server

Next, create a docker-compose.yml file in that directory with the following content:

docker-compose.yml

services:
  crossonic:
    image: ghcr.io/juho05/crossonic-server:latest # to pin the container to a specific version replace `latest` with e.g. `v0.0.7`
    # automatically restart crossonic-server on reboot or failure
    restart: unless-stopped
    # all configuration options are provided under the `environment` key
    environment:
      # These connection settings for the database do not need to be changed if you are using this
      # example configuration.
      DB_USER: crossonic
      DB_PASSWORD: crossonic
      DB_HOST: db
      DB_PORT: 5432
      DB_NAME: crossonic

      # Base64 encoded string representing exactly 32 bytes.
      # TODO: generate with: docker run --rm -it --entrypoint crossonic-admin ghcr.io/juho05/crossonic-server gen-encryption-key
      ENCRYPTION_KEY: <key>

      # URL where crossonic-server is reachable.
      # The value of this field is used in some API responses.
      BASE_URL: "https://crossonic.example.com"
    # Map directories of your host system to directories inside the container.
    # Do not change the path right of the :.
    volumes:
      - "./cache:/cache"   # cache files
      - "./data:/data"     # cover art etc.
      # TODO: replace the left side of the : with the path to your music directory
      - "/path/to/your/music:/music" # your music files
    # To change the port where crossonic-server is accessible change the LEFT number and KEEP the right number as 8080.
    ports:
      - "8080:8080"
    depends_on:
      db:
        condition: service_healthy
        restart: true
  # Postgresql database for crossonic-server
  db:
    image: postgres:16-trixie
    restart: unless-stopped
    volumes:
      - ./postgres:/var/lib/postgresql/data
    environment:
      # Do not change these values without changing the corresponding environment variables for crossonic-server
      # and the parameters of the healthcheck test command.
      POSTGRES_PASSWORD: crossonic
      POSTGRES_USER: crossonic
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U crossonic -d crossonic"]
      interval: 15s
      retries: 5
      start_period: 30s
      start_interval: 1s
      timeout: 10s

Change /path/to/your/music to the directory path where your music files are stored.

Make sure to set the value of the ENCRYPTION_KEY option to a valid value. To generate an encryption key run:

sudo docker run --rm -it --entrypoint crossonic-admin ghcr.io/juho05/crossonic-server gen-encryption-key

Assuming the output of that command is:

[...]
Key: CSBkvrsKCm/InAf5aozmjSs/9o8xDbpbmUsZ92eAO3g

you would change ENCRYPTION_KEY: <key> to
ENCRYPTION_KEY: "CSBkvrsKCm/InAf5aozmjSs/9o8xDbpbmUsZ92eAO3g".

Caution

Crossonic-Server stores the IDs of all scanned songs as tags in the metadata of your music files. This feature can currently not be disabled. You can remove these tags automatically with the admin CLI.

Now you can start the container:

sudo docker compose up -d

If everything went well you’ll be able to access crossonic-server on port 8080 of your server. To verify everything is working correctly you can try to contact the /rest/ping endpoint:

curl "http://localhost:8080/rest/ping?f=json"

A successful response will look similar to this:

{"subsonic-response":{"status":"failed","version":"1.16.1","type":"crossonic-server","serverVersion":"0.1.1","openSubsonic":true,"crossonic":true,"crossonicVersion":"0.3.0","error":{"code":10,"message":"missing parameter 'v'"}}}

In case something does not work right you can view the logs with:

sudo docker compose logs -f crossonic

Create a user

To connect a client to the server you will need to create user credentials.

While the container is running execute (replace <name> with your desired name):

docker compose exec -it crossonic crossonic-admin users create <name>

When prompted enter your desired password and the user will be created for you. You can now connect a client app to your server with these credentials.

Next steps

Consider enabling last.fm integration to automatically fetch artist images, artist biographies and album info.

See the configuration guide for all available configuration options.