Basalt Host in Docker · Basalt Docs

Run Basalt Host as a container on a NAS or a home server, and set it up from your phone.

The Docker image is Basalt Host with no screen, in a container. It suits a NAS (Synology, Unraid, TrueNAS, QNAP and others) or any server that runs Docker. You set it up and manage it from the Basalt app, with Manage host.


Image	`ghcr.io/refora-technologies/basalt-host`
Tags	`latest`, or a version such as `1.5.0` or `1.5`
Processors	amd64 (64-bit PCs and most NAS boxes) and arm64 (Raspberry Pi and other ARM boards). Docker picks the right one by itself

On a Windows computer, use Basalt Host for Windows rather than Docker Desktop. Docker Desktop keeps containers on a network of their own, where your devices cannot find them.

Run it with Docker Compose

Make a folder for it, for example basalt, and in it a file called compose.yaml:

services:
  basalt:
    image: ghcr.io/refora-technologies/basalt-host:latest
    container_name: basalt
    network_mode: host
    environment:
      - PUID=1000
      - PGID=1000
    volumes:
      - ./config:/config
      - /srv/media:/media/Media
    restart: unless-stopped

Change /srv/media to the folder with your files, and PUID and PGID to the user and group that own them. Running id on the NAS shows yours.
Start it:
```
docker compose up -d
```

Or with docker run

docker run -d --name basalt --network host \
  -e PUID=1000 -e PGID=1000 \
  -v /srv/basalt/config:/config \
  -v /srv/media:/media/Media \
  --restart unless-stopped ghcr.io/refora-technologies/basalt-host:latest

On a NAS

In your NAS’s container app (such as Container Manager on Synology, or Docker on Unraid), add a container from the image ghcr.io/refora-technologies/basalt-host:latest, with the same settings:

Network: host
Folders: a folder of its own mounted at /config, and each folder to share mounted under /media
Environment: PUID and PGID set to the user and group that own your files
Restart: unless stopped

Set it up

Find the setup code. This shows it, with the host’s address:
```
docker exec basalt basalt-host status
```
It is in the log too: docker logs basalt.
Open Basalt on your phone or computer, on the same network. The host shows in the list as new. Choose it and type the code.
That device manages the host now. Choose Choose what it shares, and pick one of the folders under /media.

From then on, everything is done from Manage host on that device. Setting up and pairing only happen on your own network.

Settings

Setting	What it does
`/config`	The host’s identity, its paired devices and its library. Keep this folder. Lose it, and every device pairs again
`/media/...`	Each folder mounted here is a drive the host can share. Add `:ro` to mount one read only
`PUID`, `PGID`	The user and group the host runs as: the owner of your files. 1000 if not set
`BASALT_HOST_NAME`	What devices call the host at first. You can rename it any time in Manage host
`network_mode: host`	Lets devices find the host by themselves. Without it, publish `7742/tcp` and `7743/udp`, and pair with Enter the address instead in the app
`/dev/dri`	Pass it in (`devices: ["/dev/dri:/dev/dri"]`) for faster video conversion with Intel or AMD graphics

To share more than one folder, mount each under /media, for example /srv/films:/media/Films and /srv/photos:/media/Photos, and choose between them in Manage host. The host shares one at a time.

Update it

A container never updates itself: you update it by pulling the new image. When a new version is out, Manage host and basalt-host status both say so. Then, in the folder with compose.yaml:

docker compose pull && docker compose up -d

Everything in /config carries over: the same host, with the same devices and settings.

If you use a tool that updates containers for you, such as Watchtower, it works with this image like any other.

Check where the image came from

Every published image is signed, and carries a record of the GitHub workflow that built it from the public source. With the GitHub CLI:

gh attestation verify oci://ghcr.io/refora-technologies/basalt-host:latest --owner refora-technologies

If the device that manages it is lost

docker exec basalt basalt-host setup-code --reset

The next device to pair with the new code manages the host too. Remove the lost device in Manage host afterwards.