Skip to content

Start Starling directly from its published image #6

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
SetZero merged 2 commits into from
Oct 1, 2026
Merged

Start Starling directly from its published image #6

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
7601449
Default Starling quickstart to a single docker run command
SetZero Oct 1, 2026
a910de1
Clarify the Compose configuration mount
SetZero Oct 1, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 18 additions & 20 deletions src/content/docs/server/docker.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,43 +1,41 @@
---
title: Run Starling with Docker
description: Start the current Fancy Mumble server using Starling's maintained Compose deployment.
description: Start Starling with the published GitHub container image.
---

Starling is the current Fancy Mumble server. Its repository contains the Compose file and the matching configuration file. For an existing deployment, follow [Migrating to Starling](/server/migrating-to-starling/).
Starling is the current Fancy Mumble server. With Docker installed and running, start its published image directly. For an existing deployment, follow [Migrating to Starling](/server/migrating-to-starling/).

## Start a server

~~~sh
git clone https://github.com/Fancy-Mumble/starling.git
cd starling
STARLING_IMAGE=ghcr.io/fancy-mumble/starling:latest docker compose up -d --wait
docker compose logs gateway
docker run -d --name starling --restart unless-stopped -p 64738:64738/tcp -p 64738:64738/udp -p 8080:8080 -p 64740:64740 -v starling-data:/var/lib/starling ghcr.io/fancy-mumble/starling:latest
~~~

On Windows PowerShell, set the image with `$env:STARLING_IMAGE='ghcr.io/fancy-mumble/starling:latest'` before running `docker compose up -d --wait`.
The same command works in PowerShell. Docker downloads the image automatically; its default starts all services in one container.

Connect Fancy Mumble to localhost:64738. On first boot Starling creates a self-signed server certificate and a SuperUser password. In the distributed stack, find the password in `docker compose logs userdata`; in the all-in-one service, check `docker compose logs starling`. Save it. Keep the starling-data volume: it holds the certificate, accounts, channels, and service data.
Connect Fancy Mumble to **localhost:64738**. On first boot Starling creates a self-signed server certificate and a SuperUser password. Run `docker logs starling` to find the password and save it. The **starling-data** volume preserves the generated configuration, certificate, accounts, channels, and service data.

## Configure and operate

To build from source, use:
The container generates a starter configuration on first run. See [Configuration](/server/config/) for changing settings. Set a public file-server URL that other members can reach before sharing files outside your machine. See [Ports and networking](/server/network/) for remote access and feature-specific media ports.

~~~sh
docker compose up -d --wait --build
docker logs -f starling
docker stop starling
docker start starling
~~~

The Compose file also supports a single-container deployment with the starling service. Start that service by name; it replaces the distributed services.
Stopping or removing the container keeps its named data volume. Deleting **starling-data** deletes its configuration, certificate, and databases. See [Upgrade and backup](/server/upgrade/).

## Configure and operate

Edit deploy/starling.toml before starting the distributed stack. The file is mounted into every service. Set an instance name and password under the instances tables. For a single process, start with starling.example.toml instead. See [Configuration](/server/config/).
## Distributed deployment or source builds

The Compose deployment publishes TCP and UDP port 64738 and HTTP port 8080 for files. Its sample public URL is localhost:8080; set a URL that other users can reach before sharing files outside your machine. See [Ports and networking](/server/network/).
Use the repository's Compose deployment when you want separate services or a local source build:

~~~sh
docker compose ps
docker compose logs -f gateway
docker compose down
git clone https://github.com/Fancy-Mumble/starling.git
cd starling
~~~

Docker Compose down keeps the data volume. Adding -v deletes it, including the server certificate and database. See [Upgrade and backup](/server/upgrade/).
Edit **deploy/starling.toml** for the distributed stack. To use the published image, set `STARLING_IMAGE=ghcr.io/fancy-mumble/starling:latest` in a `.env` file, then run `docker compose up -d --wait`. To build locally, run `docker compose up -d --wait --build`.

For current Compose options, see the [Starling README](https://github.com/Fancy-Mumble/starling#install) and [Compose file](https://github.com/Fancy-Mumble/starling/blob/main/docker-compose.yml).
The Compose **starling** service is the single-container alternative: `docker compose up -d --wait starling` starts it instead of the distributed services. It uses the same **deploy/starling.toml** mount with service routing overrides; see the [Compose file](https://github.com/Fancy-Mumble/starling/blob/main/docker-compose.yml) for its mounts and settings.
Loading