dst-server-kit

Run a modded DST server in 5 minutes.

No Lua config. No manual setup.

• Web admin panel (mods, snapshots, commands, logs)
• One-click install (Windows + Linux)
• Docker-based, multi-instance ready
• Snapshot and restore anytime

Quick Install

Docker is required. git is not required for the one-line commands below.

Linux

curl -fsSL https://raw.githubusercontent.com/c01-in/dst-server-kit/master/scripts/install-qg-dst.sh | bash

Windows PowerShell

powershell -NoProfile -ExecutionPolicy Bypass -Command "& ([scriptblock]::Create((irm 'https://raw.githubusercontent.com/c01-in/dst-server-kit/master/scripts/install-qg-dst.ps1'))) -Mode image"

Both commands default to the prebuilt-image install flow:

• pull prebuilt GHCR images
• download only the compose/env/template files needed for image deployment
• auto-pick a default install directory
• detect an existing install in that directory and refresh it in place
• keep the current port group for the same instance unless you explicitly override it

For stable installs, use the one-line commands on the GitHub Releases page. Those release-pinned commands install the matching v* image tags instead of latest.

Why this project?

Managing a DST server is painful:

• Editing Lua files
• Manually installing mods
• No easy backup / restore
• Debugging via logs only

This project fixes that with a modern web UI.

Default login

First login:

• Username: admin
• Password: change-me

After login, the UI will immediately prompt you to set a new password.

Install prerequisites

• Docker installed
• Docker daemon running
• git only needed for repository-clone workflows outside the default image-mode one-line install path
• Linux server needs bash
• Windows server can use PowerShell 5.1+ or PowerShell 7

One-click install

Linux / SSH

curl -fsSL https://raw.githubusercontent.com/c01-in/dst-server-kit/master/scripts/install-qg-dst.sh | bash

Linux installer behavior:

• Uses .env.example as default seed for target .env (or --env-file if provided)
• Checks occupied ports and auto-picks a non-conflicting full port group
• If reinstalling the same Instance, reuses that instance's previous ports by default
• Auto-selects ~/qg-dst-server for main, or ~/qg-dst-<instance> for other instances
• In --mode image, a GitHub repo URL can install without git by downloading only the image-mode compose file and required templates
• When run directly from the GitHub raw URL, image mode is the default

Windows / double click

Download the repository, then double-click:

scripts\install-qg-dst.cmd

The Windows launcher will:

• Ask for the instance name and admin port
• Pre-fill the install directory from that instance name
• Ask whether the server should be LAN-only or public
• If you choose public, ask for the Klei server token
• Try to start Docker Desktop if needed
• Use the local installer script
• Open the admin page after install
• If an existing install is detected, ask whether to force reinstall
• Auto-assign a non-conflicting port set for new instances by default
• Work from a downloaded ZIP without requiring git, as long as the installer is running from that local extracted folder
• In image mode, work from the default GitHub repo URL without requiring git by downloading only the compose/template files needed for prebuilt-image deployment

Windows / PowerShell one-liner

powershell -NoProfile -ExecutionPolicy Bypass -Command "& ([scriptblock]::Create((irm 'https://raw.githubusercontent.com/c01-in/dst-server-kit/master/scripts/install-qg-dst.ps1'))) -Mode image"

One-line remote execution behavior:

• Defaults to image mode for remote repo URLs
• Uses %USERPROFILE%\qg-dst-server for main, or %USERPROFILE%\qg-dst-<instance> for other instances
• Does not require git
• Downloads only the compose/template files needed for prebuilt-image deployment

When you launch from this repository's scripts folder, the default install directory is %USERPROFILE%\qg-dst-server for main, or %USERPROFILE%\qg-dst-<instance> for other instances, so the source checkout stays untouched. If you launch the PowerShell installer from an existing deployed instance's scripts folder, the default is that instance folder. Otherwise, the default is the current folder plus qg-dst-server or qg-dst-<instance>.

Force reinstall resets the install-time passwords and settings stored in the install directory. Docker volumes are not removed by reinstall, so world data usually stays intact unless you remove volumes separately. For an existing instance with the same Instance value, overwrite install reuses that instance's previous ports by default.

Public server token

If you want the server to be public, create a Klei server token here:

Klei server token page

Paste that token into the Windows installer prompt, or pass it to the PowerShell installer with -Token. The installer writes it to DST_SERVER_TOKEN, and the server startup script saves it into cluster_token.txt.

Custom env file

By default, the installer seeds .env from .env.example.

If you want to use your own env file, you must specify one:

./scripts/install-qg-dst.sh --env-file /path/to/my.env

powershell -NoProfile -ExecutionPolicy Bypass -File scripts\install-qg-dst.ps1 -EnvFile C:\path\to\my.env

You can also set:

• ENV_FILE_SOURCE for the bash installer
• QG_ENV_FILE for the PowerShell installer

Notes:

• The repository root .env is not used by the installer by default
• Remote helper scripts such as validate-ssh.ps1 and remote-compose.ps1 require REMOTE_PROJECT_DIR to be set explicitly in .env

Prebuilt image deployment

Good for NAS / dashboard / Portainer setups.

docker compose -f docker-compose.images.yml up -d

Default images:

• ghcr.io/c01-in/qg-dst-server:latest
• ghcr.io/c01-in/qg-dst-admin:latest

Published platform targets:

• qg-dst-server: linux/amd64
• qg-dst-admin: linux/amd64, linux/arm64

Notes:

• The DST runtime image currently targets linux/amd64 only.
• The admin image is published for both linux/amd64 and linux/arm64.
• On master, GitHub Actions publishes the latest tags automatically.
• On release tags such as v0.2.3, GitHub Actions also publishes the matching version tags.
• On release tags, GitHub Actions also creates a GitHub Release page with one-line install commands pinned to that exact version.

You can override them in .env:

• QG_DST_IMAGE
• QG_ADMIN_IMAGE

Image-mode installer inputs downloaded automatically:

• docker-compose.images.yml
• .env.example
• config/mods.list
• runtime/admin_control/modinfo.lua
• runtime/admin_control/modmain.lua
• runtime/admin_control/README.md
• runtime/admin_control/state.json initialized locally when missing

Stable local build images

The local build compose uses fixed image tags:

• qg-dst-server-dst:latest
• qg-dst-server-admin:latest

This keeps docker images easier to read across reinstall cycles.

Data location (Linux + Windows)

By default, game files and world data are stored under the install directory (bind mounts), not Docker named volumes:

• runtime/dst-install -> /opt/dst/server
• runtime/dst-data -> /data

This applies to both Linux and Windows installs.

Change password on first login

If the admin login is still using the default password, the UI sends you to the settings page right away.

You can also change the admin password later from the web UI without restarting.

Workshop startup flow

Server startup now uses this order:

1. Render mod config from mods.list
2. Check whether each configured mod is already installed on disk
3. Run HTTP legacy fallback download/install only for missing mods
4. Enforce DST_FAIL_ON_MISSING_MODS policy
5. Launch shards

Default launch includes -skip_update_server_mods (DST_SKIP_UPDATE_SERVER_MODS_ON_LAUNCH=true) so shard startup does not block on runtime workshop update. If fallback download fails, the default HTTP retry count is 2 (DST_LEGACY_RETRIES=2).

Uninstall

Double-click scripts\uninstall-qg-dst.cmd and choose what to remove.

The default install directory follows the launcher location:

• From this repository's scripts folder: %USERPROFILE%\qg-dst-server for main, or %USERPROFILE%\qg-dst-<instance> for other instances
• From a deployed instance's scripts folder: that instance folder
• Otherwise: the current folder plus qg-dst-server or qg-dst-<instance>

The uninstall launcher will ask:

• Which install directory to target
• Remove the containers too?
• Remove the deployed install directory too?
• Remove data directories (runtime) and legacy named volumes too?
• Remove images too?

The uninstall launcher refuses to target the repository source tree. The install directory is the deployed instance folder created by the installer, not your source checkout.

To clean everything, answer Y to containers, install directory, volumes, and images.

If you keep the containers, install directory, volume, and image cleanup will be skipped. If you remove images, the script will skip any image that is still used by another container.

Multi-instance tips

You can run multiple separate DST servers on the same machine by giving each instance its own install folder and unique runtime values.

What must be unique per instance

• InstallDir
• Instance
• QG_DST_CONTAINER_NAME
• QG_ADMIN_CONTAINER_NAME
• ADMIN_WEB_PORT
• DST_CLUSTER_DIR
• Server port groups used by the cluster config

By default, the installer auto-assigns a unique full port group (ADMIN_WEB_PORT + DST game/shard/auth/query ports) for new instances, so users can usually press Enter all the way through.

What you can keep the same

• The repository source files
• The default admin login
• The install method

Recommended pattern

Create one install folder per instance and launch each one with a different instance name. The installer now auto-selects the folder from Instance, so you usually do not need -InstallDir:

powershell -NoProfile -ExecutionPolicy Bypass -File scripts\install-qg-dst.ps1 -Instance main -AdminPort 8080

powershell -NoProfile -ExecutionPolicy Bypass -File scripts\install-qg-dst.ps1 -Instance test -AdminPort 8081

If you use the Windows cmd launcher, it will prompt for the same values interactively, so you can just double-click and fill in the answers.

Example instance values

• Main server:
  • Instance=main
  • InstallDir is auto-selected as %USERPROFILE%\qg-dst-server on Windows or ~/qg-dst-server on Linux
  • ADMIN_WEB_PORT=8080
  • DST_CLUSTER_DIR=QG_Cluster_main
  • QG_DST_CONTAINER_NAME=qg-main-dst-server
  • QG_ADMIN_CONTAINER_NAME=qg-main-dst-admin
• Test server:
  • Instance=test
  • InstallDir is auto-selected as %USERPROFILE%\qg-dst-test on Windows or ~/qg-dst-test on Linux
  • ADMIN_WEB_PORT=8081
  • DST_CLUSTER_DIR=QG_Cluster_test
  • QG_DST_CONTAINER_NAME=qg-test-dst-server
  • QG_ADMIN_CONTAINER_NAME=qg-test-dst-admin

World data note

The installer does not remove Docker volumes during a reinstall by default, so world data is usually kept unless you explicitly remove volumes. If you want a truly fresh world, remove volumes during uninstall or create a brand-new instance folder and volume set.

Preview

Useful scripts

• Linux installer
• Windows installer
• Windows CMD launcher
• Windows shortcut creator
• Windows uninstall script
• Windows uninstall launcher

License

This project is licensed under GNU AGPLv3 or later. See LICENSE.