Run the server in Docker

The published ghcr.io/twlite/remedia image includes the standalone server and FFmpeg 9 shared libraries for Linux AMD64 and ARM64. Docker selects your architecture automatically. You only need Docker and a configuration file. No repository checkout or build tools are required.

Choose a tagCopy Anchor Link

• dev follows the newest prerelease.
• latest follows the newest stable release. It is unavailable until a stable release is published.
• Exact release tags such as 0.1.0-dev.7 (without v) pin a version. Use these for reproducible deployments.

Create the configurationCopy Anchor Link

Create a config directory and save this as config/remedia.config.json:

{
  "listen": "0.0.0.0:8787",
  "users": [{ "username": "media-bot", "password": "env('REMEDIA_RPC_PASSWORD')" }],
  "media": {
    "allowedFileRoots": ["/media"],
    "allowedUrlHosts": ["media.example.com"],
    "allowHttp": false,

    "blockPrivateNetworks": true
  }
}

Replace media.example.com with your media provider's hostname. An empty host list denies URL playback. See configuration for other options and limits.

Create .env beside the directory, using a long random password (for example, openssl rand -hex 32):

REMEDIA_RPC_PASSWORD=replace-with-your-random-password

The image runs as UID/GID 10001. On Linux, grant that user access with sudo chown -R 10001:10001 config && sudo chmod 750 config. Docker Desktop usually handles bind-mount permissions automatically. Keep .env private and out of version control.

Run with DockerCopy Anchor Link

Run these commands from the directory containing config and .env:

docker pull ghcr.io/twlite/remedia:dev
docker run -d --name remedia --restart unless-stopped \
  --env-file .env \
  -p 127.0.0.1:8787:8787 \
  -v "$PWD/config:/config" \
  ghcr.io/twlite/remedia:dev
docker logs -f remedia

The default command is remedia serve --config /config/remedia.config.json. The directory mount persists configuration and permits atomic configuration edits by plugin commands.

Run with Docker ComposeCopy Anchor Link

Alternatively, save this as compose.yaml beside .env:

services:
  remedia:
    image: ghcr.io/twlite/remedia:dev
    restart: unless-stopped
    stop_grace_period: 30s
    env_file: .env
    ports:
      - '127.0.0.1:8787:8787'
    volumes:
      - ./config:/config

docker compose pull
docker compose up -d
docker compose logs -f remedia

A bot on the host connects to remedia://127.0.0.1:8787. A bot on the same Compose network connects to remedia://remedia:8787, using the configured account. For connections from another machine, use a TLS reverse proxy. The server binds all container interfaces, while the host port is restricted to loopback. Change the first 8787 in the port mapping to choose another host port.

Discord voice needs outbound HTTPS and UDP. No inbound UDP port is required.

Volumes and diagnosticsCopy Anchor Link

To play local files, add -v /srv/media:/media:ro to docker run, or add - /srv/media:/media:ro under Compose's volumes. Clients use container paths such as /media/song.mp3. A remote path always refers to the server's filesystem.

docker exec remedia remedia --version
docker exec remedia remedia doctor
docker exec remedia remedia --list --json

The image health check queries the local server status. It does not verify external media, Discord connectivity or published-port reachability. Logs go to stdout/stderr.

Plugin commands edit the mounted configuration. Restart afterward:

docker compose run --rm remedia plugins list
docker compose restart remedia

UpdatesCopy Anchor Link

For Compose, change the image tag when pinning a release, then run:

docker compose pull
docker compose up -d

For docker run, pull the desired tag, run docker stop remedia && docker rm remedia, and repeat the run command with that tag and the same mounts and environment file. Configuration persists on the host. Recreating the container ends active playback sessions. Clients must reconnect and restore state. Update the image instead of running remedia update inside the container.

Advanced: build the image yourselfCopy Anchor Link

The optional repository Dockerfile packages a published release. It does not compile Rust:

git clone https://github.com/twlite/remedia.git
cd remedia
docker build -f docker/Dockerfile --build-arg REMEDIA_VERSION=0.1.0-dev.7 -t remedia-local .

Use a fixed published version. For compiling the binaries from source, see installation. The repository's docker/compose.build.yaml provides an optional local image build override. GitHub API rate limits can affect builds. See docker/README.md for the supported BuildKit token secret.