GitHub - DarkMatterProductions/vintagestory: Vintage Story Server Docker Image based on the official Vintage Story server installation instructions, and extracted from server.sh for better Docker compatibility.

Docker Image References
Support
Quick Start
- Basic Server
- Server with Configuration
Security Best Practices
Data Persistence
- Mounting the Data Volume
- Recovering data from within the container
Upgrading
Container Commands
Environment Variables Reference
Configuration Options
Docker Compose Examples
Building the Image

About Vintage Story

Vintage Story is an uncompromising wilderness survival sandbox that takes everything you know from block-based games and adds authentic complexity. Progress through five metallurgical eras—from knapping flint tools to building steel production chains—using hands-on crafting systems where you actually chip stone, hammer metal on anvils, and sculpt clay voxel by voxel. The world generates with focus on realistic geology, implementing 22 rock types in proper strata, climate-driven seasons that transform gameplay, and a unique temporal horror dimension: your stability meter drains underground, spawning increasingly dangerous Drifters as it drops, while periodic temporal storms force you into fortified bunkers. Late-game mechanical power systems let you automate grinding, pulverizing, and forging with windmill-driven factories.

Choose from six character classes each with unique traits, explore a procedurally generated world spanning climate zones from tundra to desert, and tackle an optional 8-chapter story featuring dungeons, NPCs, and boss encounters. The game supports both hardcore survivalists (permadeath, harsh winters, cave-ins) and peaceful builders (creative mode, reduced combat) through extensive world customization. Multiplayer includes land claiming, while a robust C# modding API allows the ability to extend the experience infinitely. Built for survival veterans seeking genuine depth beyond the Minecraft formula.

Dedicated Server Docker Image

Vintage Story Dedicated Server Docker Image, built on Ubuntu 24.04 is based on the official Vintage Story server installation instructions and extracted from server.sh for better Docker compatibility.

Official dedicated server guide: https://wiki.vintagestory.at/Guide:Dedicated_Server

Docker Image References

Container Registries

Docker Hub: ralnoc/vintagestory
GitHub Container Registry: ghcr.io/darkmatterproductions/vintagestory

Support

For issues, questions, or contributions:

GitHub Issues: https://github.com/DarkMatterProductions/vintagestory/issues
Official Wiki: https://wiki.vintagestory.at/

Quick Start

Basic Server

⚠️ Important Note: This will use default settings and is not suitable for production use. Ensure you use environment variables or a custom configuration file for a production server.

Run a basic Vintage Story server with default settings:

docker run -d \
  --name vintagestory-server \
  -p 42420:42420/tcp \
  -p 42420:42420/udp \
  -v /path/to/your/vs/data:/vintagestory/data \
  --restart unless-stopped \
  ghcr.io/darkmatterproductions/vintagestory:latest

Server with Configuration

Run with a custom server name and settings:

docker run -d \
  --name vintagestory-server \
  -p 42420:42420/tcp \
  -p 42420:42420/udp \
  -v /path/to/your/vs/data:/vintagestory/data \
  -e VS_CFG_SERVER_NAME="My Vintage Story Server" \
  -e VS_CFG_MAX_CLIENTS=20 \
  -e VS_CFG_SERVER_PASSWORD="secret123" \
  -e ENABLE_DEBUG_LOGGING=true \
  --restart unless-stopped \
  ghcr.io/darkmatterproductions/vintagestory:latest

Important: Replace /path/to/your/vs/data with the actual path on your host machine where you want to persist server data. This ensures your world data, configurations, and mods are not lost when the container is removed or upgraded.

Security Best Practices

Always change default passwords in production environments
Change VS_RCON_SERVER_CFG_PASSWORD
Change VS_RCON_CLIENT_CFG_SERVER_SECRET_KEY
Change VS_RCON_CLIENT_CFG_SECURITY_DEFAULT_PASSWORD
Use strong, unique passwords for each setting
RCON is an unencrypted protocol, always use some form of encryption or limit to localhost access. The RCON WebUI was created to address this.

Data Persistence

Mounting the Data Volume

Always mount the /vintagestory/data volume to a persistent location on your host. This ensures:

World data is preserved across container updates
Server configurations persist
Mods are retained
Player data is not lost

Recovering data from within the container

If you inadvertently started your game without mounting the /vintagestory/data volume, you can extract your data from the container using the following command:

docker cp vintagestory-server:/vintagestory/data /path/you/want/to/save/your/vs/data

This will allow you to extract your data, and start a new container mounting the volume to the new path you have saved your data to.

Upgrading

When using ghcr.io/darkmatterproductions/vintagestory:latest or ralnoc/vintagestory:latest, the image always installs the latest version of Vintage Story.
⚠️ IMPORTANT: If you need to extract your game data from within the container, please refer to the "Recovering data from within the container" section above before proceeding with the upgrade steps.

To upgrade:

# Stop and remove old container
docker stop vintagestory-server
docker rm vintagestory-server # Ensure you have your data backed up or mounted to a volume before removing the container

# Pull latest image
docker pull ghcr.io/darkmatterproductions/vintagestory:latest

# Start new container with same volumes
docker run -d \
  --name vintagestory-server \
  -p 42420:42420/tcp \
  -p 42420:42420/udp \
  -v /path/to/your/vs/data:/vintagestory/data \
  --restart unless-stopped \
  ghcr.io/darkmatterproductions/vintagestory:latest

Or with Docker Compose:

docker-compose pull
docker-compose up -d

Container Commands

Running the Container

Basic Run

docker run -d \
  --name vintagestory-server \
  -p 42420:42420/tcp \
  -p 42420:42420/udp \
  -p 5000:5000/tcp \
  -v /path/to/your/vs/data:/vintagestory/data \
  -e VS_CFG_SERVER_NAME="My Awesome Server" \
  -e VS_CFG_SERVER_DESCRIPTION="A friendly survival server" \
  -e VS_CFG_MAX_CLIENTS=16 \
  -e VS_CFG_SERVER_PASSWORD="mypassword" \
  --restart unless-stopped \
  ghcr.io/darkmatterproductions/vintagestory:latest

Run with RCON Web Client

docker run -d \
  --name vintagestory-server \
  -p 42420:42420/tcp \
  -p 42420:42420/udp \
  -p 5000:5000/tcp \
  -v /path/to/your/vs/data:/vintagestory/data \
  -e VS_CFG_SERVER_NAME="My Awesome Server" \
  -e VS_CFG_SERVER_DESCRIPTION="A friendly survival server" \
  -e VS_CFG_MAX_CLIENTS=16 \
  -e VS_CFG_SERVER_PASSWORD="mypassword" \
  -e VS_RCON_ENABLED=true \
  --restart unless-stopped \
  ghcr.io/darkmatterproductions/vintagestory:latest

Managing the Container

Start the Container

docker start vintagestory-server

Stop the Container

docker stop vintagestory-server

Restart the Container

docker restart vintagestory-server

Remove the Container

docker stop vintagestory-server
docker rm vintagestory-server

Viewing Logs

View All Logs

docker logs vintagestory-server

Follow Logs in Real-Time

docker logs -f vintagestory-server

View Last 100 Lines

docker logs --tail 100 vintagestory-server

View Logs with Timestamps

docker logs -t vintagestory-server

View Container Statistics

docker stats vintagestory-server

Inspect Container Configuration

docker inspect vintagestory-server

Environment Variables Reference

Boolean Values

Boolean environment variables accept the following values (case-insensitive):

True: true, 1, yes, on
False: false, 0, no, off

General Logging Configuration

Control logging behavior for the Vintage Story server.

Variable	Type	Default	Description
`ENABLE_DEBUG_LOGGING`	Boolean	`false`	Enables debug level logging for troubleshooting
`ENABLE_CHAT_LOGGING`	Boolean	`false`	Enables chat message logging to server logs
`FORCE_REGENERATE_CONFIG`	Boolean	`false`	Forces regeneration of serverconfig.json on startup

Example:

docker run -d \
  --name vintagestory-server \
  -p 42420:42420/tcp \
  -p 42420:42420/udp \
  -p 5000:5000/tcp \
  -v /path/to/your/vs/data:/vintagestory/data \
  -e VS_CFG_SERVER_NAME="My Awesome Server" \
  -e VS_CFG_SERVER_DESCRIPTION="A friendly survival server" \
  -e VS_CFG_MAX_CLIENTS=16 \
  -e VS_CFG_SERVER_PASSWORD="mypassword" \
  -e ENABLE_DEBUG_LOGGING=true \
  -e ENABLE_CHAT_LOGGING=true \
  ghcr.io/darkmatterproductions/vintagestory:latest

Server Configuration Variables

These variables configure the Vintage Story game server and map to settings in serverconfig.json. All variables with the VS_CFG_ prefix override corresponding server settings.

Variable	Type	Default	Description
`VS_CFG_SERVER_NAME`	String	(from server-config.yaml)	The name of your server as displayed in the server list
`VS_CFG_SERVER_URL`	String	(from server-config.yaml)	URL to your server's website or information page
`VS_CFG_SERVER_DESCRIPTION`	String	(from server-config.yaml)	Server description shown in the server list
`VS_CFG_WELCOME_MESSAGE`	String	(from server-config.yaml)	Message displayed to players when they join
`VS_CFG_ALLOW_CREATIVE_MODE`	Boolean	(from server-config.yaml)	Whether creative mode is allowed (true/false/1/0/yes)
`VS_CFG_SERVER_IP`	String	(from server-config.yaml)	IP address the server binds to (0.0.0.0 for all interfaces)
`VS_CFG_SERVER_PORT`	Integer	(from server-config.yaml)	Port number the game server listens on (default: 42420)
`VS_CFG_SERVER_UPNP`	Boolean	(from server-config.yaml)	Enable UPnP port forwarding (true/false/1/0/yes)
`VS_CFG_SERVER_COMPRESS_PACKETS`	Boolean	(from server-config.yaml)	Enable packet compression to reduce bandwidth
`VS_CFG_ADVERTISE_SERVER`	Boolean	(from server-config.yaml)	Advertise server in the public server list
`VS_CFG_MAX_CLIENTS`	Integer	(from server-config.yaml)	Maximum number of concurrent players allowed
`VS_CFG_PASS_TIME_WHEN_EMPTY`	Boolean	(from server-config.yaml)	Whether time passes when no players are online
`VS_CFG_SERVER_PASSWORD`	String	(from server-config.yaml)	Password required to join the server (empty for no password)
`VS_CFG_MAX_CHUNK_RADIUS`	Integer	(from server-config.yaml)	Maximum chunk view distance allowed for clients
`VS_CFG_SERVER_LANGUAGE`	String	(from server-config.yaml)	Server language code (e.g., "en", "de", "fr")
`VS_CFG_ENFORCE_WHITELIST`	Boolean	(from server-config.yaml)	Whitelist enforcement mode
`VS_CFG_ANTIABUSE`	Integer	(from server-config.yaml)	Anti-abuse protection level (0=disabled, 1=enabled)
`VS_CFG_ALLOW_PVP`	Boolean	(from server-config.yaml)	Allow player-vs-player combat
`VS_CFG_HOSTED_MODE`	Boolean	(from server-config.yaml)	Enable hosted mode restrictions
`VS_CFG_HOSTED_MODE_ALLOW_MODS`	Boolean	(from server-config.yaml)	Allow mods in hosted mode

Example:

docker run -d \
  --name vintagestory-server \
  -p 42420:42420/tcp \
  -p 42420:42420/udp \
  -p 5000:5000/tcp \
  -v /path/to/your/vs/data:/vintagestory/data \
  -e VS_CFG_SERVER_NAME="My Awesome Server" \
  -e VS_CFG_SERVER_DESCRIPTION="A friendly survival server" \
  -e VS_CFG_MAX_CLIENTS=16 \
  -e VS_CFG_SERVER_PASSWORD="mypassword" \
  -e VS_RCON_ENABLED=true \
  ghcr.io/darkmatterproductions/vintagestory:latest

Note: Values marked as "(from server-config.yaml)" come from the server-config.yaml file and are only overridden if the environment variable is explicitly set.

Mod Management Variables

Control which mods are downloaded and installed on the server.

Variable	Type	Default	Description
`VS_MODS`	String	`""`	Comma-separated list of mod download paths from mods.vintagestory.at Format: `modid/filename.zip,modid2/filename2.zip`
`VS_RCON_ENABLED`	Boolean	`false`	Set to `true` to enable RCON functionality and download the RCON mod
`VS_RCON_MOD_VERSION`	String	`2.0.2`	Version of the VintageRCon mod to download when RCON is enabled

Example:

docker run -d \
  --name vintagestory-server \
  -p 42420:42420/tcp \
  -p 42420:42420/udp \
  -p 5000:5000/tcp \
  -v /path/to/your/vs/data:/vintagestory/data \
  -e VS_CFG_SERVER_NAME="My Awesome Server" \
  -e VS_CFG_SERVER_DESCRIPTION="A friendly survival server" \
  -e VS_CFG_MAX_CLIENTS=16 \
  -e VS_CFG_SERVER_PASSWORD="mypassword" \
  -e VS_RCON_ENABLED=true \
  -e VS_MODS="72291/vsvanillaplus_0.1.5.zip,75006/BetterRuinsv0.5.7.zip,73792/configlib_1.10.14.zip" \
  -e VS_RCON_ENABLED=true \
  -e VS_RCON_MOD_VERSION="2.0.2" \
  ghcr.io/darkmatterproductions/vintagestory:latest

RCON Server Configuration

Configure the RCON server connection settings. These control how the RCON web client connects to the Vintage Story server's RCON interface.

Variable	Type	Default	Description
`VS_RCON_SERVER_CFG_PORT`	Integer	`42425`	Port number the Vintage Story RCON server listens on
`VS_RCON_SERVER_CFG_IP`	String	`127.0.0.1`	IP address of the Vintage Story RCON server
`VS_RCON_SERVER_CFG_PASSWORD`	String	`changeme`	Password for authenticating to the RCON server ⚠️ CHANGE IN PRODUCTION
`VS_RCON_SERVER_CFG_TIMEOUT`	Integer	`20`	Connection timeout in seconds
`VS_RCON_SERVER_CFG_MAXCONNECTIONS`	Integer	`10`	Maximum number of concurrent RCON connections allowed

Example:

docker run -d \
  --name vintagestory-server \
  -p 42420:42420/tcp \
  -p 42420:42420/udp \
  -p 5000:5000/tcp \
  -v /path/to/your/vs/data:/vintagestory/data \
  -e VS_CFG_SERVER_NAME="My Awesome Server" \
  -e VS_CFG_SERVER_DESCRIPTION="A friendly survival server" \
  -e VS_CFG_MAX_CLIENTS=16 \
  -e VS_CFG_SERVER_PASSWORD="mypassword" \
  -e VS_RCON_ENABLED=true \
  -e VS_RCON_SERVER_CFG_PORT=42425 \
  -e VS_RCON_SERVER_CFG_PASSWORD="secure-rcon-password" \
  -e VS_RCON_SERVER_CFG_TIMEOUT=30 \
  ghcr.io/darkmatterproductions/vintagestory:latest

RCON Web Client Configuration

Configure the RCON web client application that provides a browser-based interface for server administration.
Note: Web Client leverages the Async mode for the python library rcon to communicate with the server's RCON interface, so the RCON server must be enabled and properly configured for the web client to function.

Server Settings

Variable	Type	Default	Description
`VS_RCON_CLIENT_CFG_SERVER_HOST`	String	`0.0.0.0`	Host address the web client listens on (0.0.0.0 for all interfaces)
`VS_RCON_CLIENT_CFG_SERVER_PORT`	Integer	`5000`	Port number the web client listens on
`VS_RCON_CLIENT_CFG_SERVER_SECRET_KEY`	String	`vintage-story-rcon-...`	Secret key for session encryption ⚠️ CHANGE IN PRODUCTION

RCON Connection Settings

Variable	Type	Default	Description
`VS_RCON_CLIENT_CFG_RCON_DEFAULT_HOST`	String	`localhost`	Default RCON host to connect to Value must match `VS_RCON_SERVER_CFG_IP`
`VS_RCON_CLIENT_CFG_RCON_DEFAULT_PORT`	Integer	`42425`	Default RCON port to connect to Value must match `VS_RCON_SERVER_CFG_PORT`
`VS_RCON_CLIENT_CFG_RCON_PASSWORD`	String	`changeme`	RCON password for authentication ⚠️ CHANGE IN PRODUCTION Value must match `VS_RCON_SERVER_CFG_PASSWORD`
`VS_RCON_CLIENT_CFG_RCON_LOCKED_ADDRESS`	Boolean	`false`	Lock RCON connection to default host/port (true/false)
`VS_RCON_CLIENT_CFG_RCON_TIMEOUT`	Integer	`10`	RCON connection timeout in seconds
`VS_RCON_CLIENT_CFG_RCON_MAX_MESSAGE_SIZE`	Integer	`4096`	Maximum RCON message size in bytes

Security Settings

Variable	Type	Default	Description
`VS_RCON_CLIENT_CFG_SECURITY_REQUIRE_AUTH`	Boolean	`true`	Require authentication to access the web client
`VS_RCON_CLIENT_CFG_SECURITY_TRADITIONAL_LOGIN_ENABLED`	Boolean	`true`	Enable traditional username/password login
`VS_RCON_CLIENT_CFG_SECURITY_DEFAULT_USERNAME`	String	`admin`	Default username for traditional login ⚠️ CHANGE IN PRODUCTION
`VS_RCON_CLIENT_CFG_SECURITY_DEFAULT_PASSWORD`	String	`changeme`	Default password for traditional login ⚠️ CHANGE IN PRODUCTION
`VS_RCON_CLIENT_CFG_SECURITY_MAX_LOGIN_ATTEMPTS`	Integer	`5`	Maximum login attempts before lockout
`VS_RCON_CLIENT_CFG_SECURITY_LOCKOUT_DURATION`	Integer	`300`	Account lockout duration in seconds after max attempts

OAuth Settings

Variable	Type	Default	Description
`VS_RCON_CLIENT_CFG_SECURITY_OAUTH_ENABLED`	Boolean	`true`	Enable OAuth authentication providers
`VS_RCON_CLIENT_CFG_SECURITY_OAUTH_AUTHORIZED_EMAILS`	String	`admin@example.com,...`	Comma-separated list of authorized email addresses for OAuth login

⚠️ Important Note: If you do not have access to a reverse proxy (such as NGINX or HAProxy) that can handle SSL/TLS certificates and port mapping, you should disable OAuth and use traditional username/password authentication instead. Most OAuth providers require HTTPS for security, which is not provided directly by the Docker container.

Provider Redirect URIs

All provider redirect URIs must be configured in the provider's app settings to point to your application. Below are the URIs for each provider. Replace yourdomain.com with your actual domain. IMPORTANT NOTE: Be aware most providers require HTTPS for the URL.

URI Examples

Google: https://yourdomain.com/login/oauth/google/authorize
Facebook: https://yourdomain.com/login/oauth/facebook/authorize
GitHub: https://yourdomain.com/login/oauth/github/authorize
Apple: https://yourdomain.com/login/oauth/apple/authorize

Provider Registration Links

Provider	Registration URL
Google	https://console.cloud.google.com/
Facebook	https://developers.facebook.com/
GitHub	https://github.com/settings/developers
Apple	https://developer.apple.com/account/

Google OAuth

Variable	Type	Default	Description
`VS_RCON_CLIENT_CFG_SECURITY_OAUTH_GOOGLE_ENABLED`	Boolean	`true`	Enable Google OAuth login
`VS_RCON_CLIENT_CFG_SECURITY_OAUTH_GOOGLE_CLIENT_ID`	String	`your-google-client-id...`	Google OAuth client ID
`VS_RCON_CLIENT_CFG_SECURITY_OAUTH_GOOGLE_CLIENT_SECRET`	String	`your-google-client-secret`	Google OAuth client secret

Go to Google Cloud Console
Create a new project or select an existing one
Navigate to "APIs & Services" > "Credentials"
Click "Create Credentials" > "OAuth client ID"
Choose "Web application" as the application type
Add authorized redirect URIs:

https://yourdomain.com/login/oauth/google/authorize

Copy the Client ID and Client Secret

Facebook OAuth

Variable	Type	Default	Description
`VS_RCON_CLIENT_CFG_SECURITY_OAUTH_FACEBOOK_ENABLED`	Boolean	`false`	Enable Facebook OAuth login
`VS_RCON_CLIENT_CFG_SECURITY_OAUTH_FACEBOOK_CLIENT_ID`	String	`your-facebook-app-id`	Facebook OAuth app ID
`VS_RCON_CLIENT_CFG_SECURITY_OAUTH_FACEBOOK_CLIENT_SECRET`	String	`your-facebook-app-secret`	Facebook OAuth app secret

Go to Facebook Developers
Create a new app or select an existing one
Add the "Facebook Login" product
In "Facebook Login" settings, add Valid OAuth Redirect URIs:

https://yourdomain.com/login/oauth/facebook/authorize (for production)

Copy the App ID and App Secret from Settings > Basic

GitHub OAuth

Variable	Type	Default	Description
`VS_RCON_CLIENT_CFG_SECURITY_OAUTH_GITHUB_ENABLED`	Boolean	`false`	Enable GitHub OAuth login
`VS_RCON_CLIENT_CFG_SECURITY_OAUTH_GITHUB_CLIENT_ID`	String	`your-github-client-id`	GitHub OAuth client ID
`VS_RCON_CLIENT_CFG_SECURITY_OAUTH_GITHUB_CLIENT_SECRET`	String	`your-github-client-secret`	GitHub OAuth client secret

Go to GitHub Developer Settings
Click "New OAuth App"
Fill in the application details:

Authorization callback URL: https://yourdomain.com/login/oauth/github/authorize

Copy the Client ID and generate a Client Secret

Apple OAuth

Variable	Type	Default	Description
`VS_RCON_CLIENT_CFG_SECURITY_OAUTH_APPLE_ENABLED`	Boolean	`false`	Enable Apple OAuth login
`VS_RCON_CLIENT_CFG_SECURITY_OAUTH_APPLE_CLIENT_ID`	String	`your-apple-service-id`	Apple OAuth service ID
`VS_RCON_CLIENT_CFG_SECURITY_OAUTH_APPLE_CLIENT_SECRET`	String	`your-apple-client-secret`	Apple OAuth client secret
`VS_RCON_CLIENT_CFG_SECURITY_OAUTH_APPLE_TEAM_ID`	String	`your-apple-team-id`	Apple Developer Team ID
`VS_RCON_CLIENT_CFG_SECURITY_OAUTH_APPLE_KEY_ID`	String	`your-apple-key-id`	Apple OAuth key ID

Logging Settings

Variable	Type	Default	Description
`VS_RCON_CLIENT_CFG_LOGGING_LOG_COMMANDS`	Boolean	`true`	Log RCON commands to file
`VS_RCON_CLIENT_CFG_LOGGING_LOG_FILE`	String	`logs/rcon.log`	Path to RCON client log file
`VS_RCON_CLIENT_CFG_LOGGING_LOG_LEVEL`	String	`INFO`	Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)

Example (RCON with OAuth):

docker run -d \
  --name vintagestory-server \
  -p 42420:42420/tcp \
  -p 42420:42420/udp \
  -p 5000:5000/tcp \
  -v /path/to/your/vs/data:/vintagestory/data \
  -e VS_CFG_SERVER_NAME="My Awesome Server" \
  -e VS_CFG_SERVER_DESCRIPTION="A friendly survival server" \
  -e VS_CFG_MAX_CLIENTS=16 \
  -e VS_CFG_SERVER_PASSWORD="mypassword" \
  -e VS_RCON_ENABLED=true \
  -e VS_RCON_SERVER_CFG_PASSWORD="my-secure-rcon-password" \
  -e VS_RCON_CLIENT_CFG_SERVER_SECRET_KEY="my-unique-secret-key-change-me" \
  -e VS_RCON_CLIENT_CFG_SECURITY_DEFAULT_PASSWORD="web-admin-password" \
  -e VS_RCON_CLIENT_CFG_SECURITY_OAUTH_GOOGLE_ENABLED=true \
  -e VS_RCON_CLIENT_CFG_SECURITY_OAUTH_GOOGLE_CLIENT_ID="your-google-id.apps.googleusercontent.com" \
  -e VS_RCON_CLIENT_CFG_SECURITY_OAUTH_GOOGLE_CLIENT_SECRET="your-google-secret" \
  -e VS_RCON_CLIENT_CFG_SECURITY_OAUTH_AUTHORIZED_EMAILS="admin@example.com,player@example.com" \
  --restart unless-stopped \
  ghcr.io/darkmatterproductions/vintagestory:latest

Configuration Options

There are four options for handling configuration of the Vintage Story server:

1. Default Configuration

Use the default configuration as defined within the Docker image.

Not recommended for production use.

2. Pre-created serverconfig.json

Pre-create the serverconfig.json configuration file in your mapped data directory. This file will be used by the server on the first run.

# Create your serverconfig.json in the data directory before starting
docker run -d \
  -v /path/to/your/vs/data:/vintagestory/data \
  ghcr.io/darkmatterproductions/vintagestory:latest

3. Custom server-config.yaml

Create an updated server-config.yaml and mount it into the container at /vintagestory/server-config.yaml. This will cause the server to generate a serverconfig.json file based on the provided YAML configuration.

docker run -d \
  -v /path/to/your/vs/data:/vintagestory/data \
  -v /path/to/your/server-config.yaml:/vintagestory/server-config.yaml \
  ghcr.io/darkmatterproductions/vintagestory:latest

4. Environment Variables

Use environment variables to override specific configuration options. See the Environment Variables Reference section above.

docker run -d \
  -v /path/to/your/vs/data:/vintagestory/data \
  -e VS_CFG_SERVER_NAME="My Server" \
  -e VS_CFG_MAX_CLIENTS=20 \
  ghcr.io/darkmatterproductions/vintagestory:latest

Priority Order: Environment variables override values in server-config.yaml, which override default values.

Docker Compose Examples

Basic Server

version: '3.8'

services:
  vintagestory-server:
    image: ghcr.io/darkmatterproductions/vintagestory:latest
    container_name: vintagestory-server
    ports:
      - "42420:42420/tcp"
      - "42420:42420/udp"
    volumes:
      - /path/to/your/vs/data:/vintagestory/data
    environment:
      - ENABLE_DEBUG_LOGGING=false
      - ENABLE_CHAT_LOGGING=true
      - VS_CFG_SERVER_NAME="My Awesome Server"
      - VS_CFG_SERVER_DESCRIPTION="A friendly survival server"
      - VS_CFG_MAX_CLIENTS=16
      - VS_CFG_SERVER_PASSWORD="mypassword"
    restart: unless-stopped

Start the server:

docker-compose up -d

Server with RCON and OAuth

version: '3.8'

services:
  vintagestory-server:
    image: ghcr.io/darkmatterproductions/vintagestory:latest
    container_name: vintagestory-server
    ports:
      - "42420:42420/tcp"
      - "42420:42420/udp"
      - "5000:5000/tcp"
    volumes:
      - /path/to/your/vs/data:/vintagestory/data
    environment:
      # Server Configuration
      - VS_CFG_SERVER_NAME="My Awesome Server"
      - VS_CFG_SERVER_DESCRIPTION="A friendly survival server"
      - VS_CFG_MAX_CLIENTS=16
      - VS_CFG_SERVER_PASSWORD="mypassword"
      
      # RCON Mod
      - VS_RCON_ENABLED=true
      - VS_RCON_MOD_VERSION=2.0.0
      
      # RCON Server
      - VS_RCON_SERVER_CFG_PORT=42425
      - VS_RCON_SERVER_CFG_PASSWORD=rcon-password
      
      # RCON Web Client
      - VS_RCON_CLIENT_CFG_SERVER_PORT=5000
      - VS_RCON_CLIENT_CFG_SERVER_SECRET_KEY=my-secret-key-change-me
      - VS_RCON_CLIENT_CFG_SECURITY_DEFAULT_PASSWORD=admin-password
      
      # OAuth
      - VS_RCON_CLIENT_CFG_SECURITY_OAUTH_GOOGLE_ENABLED=true
      - VS_RCON_CLIENT_CFG_SECURITY_OAUTH_GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
      - VS_RCON_CLIENT_CFG_SECURITY_OAUTH_GOOGLE_CLIENT_SECRET=your-client-secret
      - VS_RCON_CLIENT_CFG_SECURITY_OAUTH_AUTHORIZED_EMAILS=admin@example.com,user@example.com
      
      # Mods
      - VS_MODS=12345/mod1.zip,67890/mod2.zip
    restart: unless-stopped

Docker Compose with Build

Build the image from source with specific version:

version: '3.8'

services:
  vintagestory-server:
    build:
      context: .
      args:
        VS_VERSION: 1.21.6
        DOTNET_VERSION: 8.0
    image: vintagestory:1.21.6
    container_name: vintagestory-server
    ports:
      - "42420:42420/tcp"
      - "42420:42420/udp"
    volumes:
      - /path/to/your/vs/data:/vintagestory/data
    environment:
      - ENABLE_DEBUG_LOGGING=true
      - VS_CFG_SERVER_NAME="My Awesome Server"
      - VS_CFG_SERVER_DESCRIPTION="A friendly survival server"
      - VS_CFG_MAX_CLIENTS=16
      - VS_CFG_SERVER_PASSWORD="mypassword"
    restart: unless-stopped

Build and start:

docker-compose up -d --build

Building the Image

Build with Specific Version

docker build \
  -t vintagestory:1.21.6 \
  --build-arg VS_VERSION=1.21.6 \
  --build-arg DOTNET_VERSION=8.0 \
  .

Build with Environment Variables

export VS_VERSION=1.21.6
export DOTNET_VERSION=8.0

docker build \
  -t vintagestory:$VS_VERSION \
  --build-arg VS_VERSION=$VS_VERSION \
  --build-arg DOTNET_VERSION=$DOTNET_VERSION \
  .

Build Arguments

Argument	Description	Default
`VS_VERSION`	Version of Vintage Story to install	(required)
`DOTNET_VERSION`	Version of .NET SDK to use	`8.0`

Name		Name	Last commit message	Last commit date
Latest commit History 266 Commits
.continue/mcpServers		.continue/mcpServers
.teamcity		.teamcity
examples		examples
images		images
toolslib		toolslib
vintage_rcon_client		vintage_rcon_client
.gitignore		.gitignore
CODEOWNERS		CODEOWNERS
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
build-dev-publish.sh		build-dev-publish.sh
build-dev.sh		build-dev.sh
build-release.sh		build-release.sh
docker-compose.yml		docker-compose.yml
entrypoint.sh		entrypoint.sh
generate-config.py		generate-config.py
script_handler.py		script_handler.py
semver.py		semver.py
server-config.yaml		server-config.yaml
vintage-story-version.yaml		vintage-story-version.yaml
vs-cli		vs-cli

Folders and files

Latest commit

History

Repository files navigation

Table of Contents

About Vintage Story

Dedicated Server Docker Image

Docker Image References

Container Registries

Support

Quick Start

Basic Server

Server with Configuration

Security Best Practices

Data Persistence

Mounting the Data Volume

Recovering data from within the container

Upgrading

Container Commands

Running the Container

Basic Run

Run with RCON Web Client

Managing the Container

Start the Container

Stop the Container

Restart the Container

Remove the Container

Viewing Logs

View All Logs

Follow Logs in Real-Time

View Last 100 Lines

View Logs with Timestamps

View Container Statistics

Inspect Container Configuration

Environment Variables Reference

Boolean Values

General Logging Configuration

Server Configuration Variables

Mod Management Variables

RCON Server Configuration

RCON Web Client Configuration

Server Settings

RCON Connection Settings

Security Settings

OAuth Settings

Provider Redirect URIs

URI Examples

Provider Registration Links

Google OAuth

Facebook OAuth

GitHub OAuth

Apple OAuth

Logging Settings

Configuration Options

1. Default Configuration

2. Pre-created serverconfig.json

3. Custom server-config.yaml

4. Environment Variables

Docker Compose Examples

Basic Server

Server with RCON and OAuth

Docker Compose with Build

Building the Image

Build with Specific Version

Build with Environment Variables

Build Arguments

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 23

Packages 0

Uh oh!

Uh oh!

Contributors

Packages