Drahkar Posted December 4, 2025 Report Posted December 4, 2025 (edited) 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, suggestions, or contributions: GitHub Issues: https://github.com/DarkMatterProductions/vintagestory/issues Important Note: When upgrading, ALWAYS backup your existing data to ensure there is a clean recovery path. 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 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. Container Commands Running the Container Basic Run 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 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_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 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 \ -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 Integer (from server-config.yaml) Whitelist enforcement mode (0=disabled, 1=enabled) 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 \ -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_CFG_ALLOW_PVP=false \ -e VS_CFG_ADVERTISE_SERVER=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 true Set to true to enable RCON functionality and download the RCON mod VS_RCON_MOD_VERSION String 2.0.0 Version of the VintageRCon mod to download when RCON is enabled Example: docker run -d \ -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.0" \ 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 \ -p 42425:42425/tcp \ -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 VS_RCON_CLIENT_CFG_RCON_DEFAULT_PORT Integer 42425 Default RCON port to connect to 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 \ -p 42420:42420/tcp \ -p 42420:42420/udp \ -p 42425:42425/tcp \ -p 5000:5000/tcp \ -v /path/to/your/vs/data:/vintagestory/data \ -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 Vintage Story Server - VS_CFG_MAX_CLIENTS=16 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" - "42425:42425/tcp" - "5000:5000/tcp" volumes: - /path/to/your/vs/data:/vintagestory/data environment: # Server Configuration - VS_CFG_SERVER_NAME=My Modded Server - VS_CFG_MAX_CLIENTS=20 - 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 Custom Build Server 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 Notes Boolean Values Boolean environment variables accept the following values (case-insensitive): True: true, 1, yes, on False: false, 0, no, off 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 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 Upgrading When using ghcr.io/darkmatterproductions/vintagestory:latest or ralnoc/vintagestory:latest, the image always installs the latest version of Vintage Story. 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 Edited Wednesday at 11:02 AM by Drahkar Updated Security Best Practices documentation. 2 1
Alexander Wilhelm Benedictus Posted December 5, 2025 Report Posted December 5, 2025 This is so useful when trying to set up a Vintage Story server on an opensuse. In theory it should be quite stable even on tumbleweed. I couldn't get the docker get the image form ghcr.io/darkmatterproductions/vintagestory, it just gave unauthorized error even if I was logged in ghcr.io on docker. Maybe it's private or not pushed there? However, I did manage to get it working by pulling the repo from github and then just building the image locally. Thank you!
Drahkar Posted December 5, 2025 Author Report Posted December 5, 2025 I'm glad this has been helpful! It was one of the first things I ran into, when I started playing. I generally don't play on my local machine, opting to instead host it on a another one. That way if friends want to play, they can do so without being at my schedule's mercy. Also, thank you for letting me know about the access issue on the packages at the Github Registry. I've fixed that, and it should work fine now. The repository permissions got mixed up when I switched the repo public, after getting the image to build and run correctly. I'm currently working on finding a way to detect when a new version and new build version of the server is available, so that I can automatically kick off the build process for the images. But even without that, I plan to keep the images up to date for those who don't have the ability to run the docker build process themselves. I should have the current build version posted to the registry tonight.
SneakyHomeless Posted January 15 Report Posted January 15 (edited) Hey, I can't manage to get it to work, getting an error saying it can't locate package `aspnetcore-runtime-8`. This is on your latest version, I will submit an Issue on github as I really don't know my stuff around this, would be glad if you could help! Thanks for the work. Edit: I got it working by using `apt-get dotnet-sdk-${DOTNET_VERSION}.0` Instead of the previous aspnetcore Edited January 15 by SneakyHomeless
Drahkar Posted January 15 Author Report Posted January 15 Thank you for calling the issue out. I'm assuming that your actively building the image, instead of just using the published on. I'll get online tonight to update the Dockerfile. The pre-built images work as is.
bughazard Posted January 18 Report Posted January 18 Howdy, I've somewhat recently switched to Linux (Debian 13) and I'm not particularly familiar with Docker, so please bear with me if you think I have missed something obvious here. I've been trying to get a dedicated server working with my computer for a few weeks now. I ran the provided command to run the Docker container, pointing the file path towards a new empty directory (empty other than a config file). It doesn't throw any errors and the logs show that the server is active, but when I try to connect to it with my IP address it just times out. I'm imagining I was supposed to do something major before running this but I'm not really sure what it is... Please help me out there, haha. Thank you for your help.
Drahkar Posted January 19 Author Report Posted January 19 Hey there! Can you paste the exact command you are using? And the docker-compose.yaml file, if you are using it.
bughazard Posted January 19 Report Posted January 19 Yes, here is the command I am using: docker run -d \ --name vintagestory-server \ -p 42420:42420/tcp \ -p 42420:42420/udp \ -v /home/username/Server \ -e ENABLE_DEBUG_LOGGING=true \ -e ENABLE_CHAT_LOGGING=true \ -e VS_CFG_SERVER_NAME="My Vintage Story Server" \ --restart unless-stopped \ ghcr.io/darkmatterproductions/vintagestory [I have replaced my username with "username" as it contains my full name] I used a serverconfig.json file, which I copied from the one that is in the singleplayer game files and mildly edited to disable the whitelist, specify the port, and added a temporary password (I planned on editing this in more depth after I got the server working). I placed in the home/username/Server folder: Spoiler { "FileEditWarning": "PLEASE NOTE: This file is also loaded when you start a single player world. If you want to run a dedicated server without affecting single player, we recommend you install the game into a different folder and run the server from there.", "ConfigVersion": "1.9", "ServerName": "My Vintage Story Server", "ServerUrl": null, "ServerDescription": "Welcome to my server", "WelcomeMessage": "Welcome {0}, may you survive well and prosper", "Ip": null, "Port": 42420, "Upnp": false, "CompressPackets": true, "AdvertiseServer": false, "MaxClients": 5, "MaxClientsInQueue": 0, "PassTimeWhenEmpty": false, "MasterserverUrl": "http://masterserver.vintagestory.at/api/v1/servers/", "ModDbUrl": "https://mods.vintagestory.at/", "ClientConnectionTimeout": 150, "EntityDebugMode": false, "Password": "password", "MapSizeX": 1024000, "MapSizeY": 256, "MapSizeZ": 1024000, "ServerLanguage": "en", "MaxChunkRadius": 12, "TickTime": 33.333332, "SpawnCapPlayerScaling": 0.5, "BlockTickChunkRange": 5, "MaxMainThreadBlockTicks": 10000, "RandomBlockTicksPerChunk": 16, "BlockTickInterval": 300, "SkipEveryChunkRow": 0, "SkipEveryChunkRowWidth": 0, "Roles": [ { "Code": "suvisitor", "PrivilegeLevel": -1, "Name": "Survival Visitor", "Description": "Can only visit this world and chat but not use/place/break anything", "DefaultSpawn": null, "ForcedSpawn": null, "Privileges": [ "chat" ], "RuntimePrivileges": [], "DefaultGameMode": 1, "Color": "Green", "LandClaimAllowance": 0, "LandClaimMinSize": { "X": 5, "Y": 5, "Z": 5 }, "LandClaimMaxAreas": 3, "AutoGrant": false }, { "Code": "crvisitor", "PrivilegeLevel": -1, "Name": "Creative Visitor", "Description": "Can only visit this world, chat and fly but not use/place/break anything", "DefaultSpawn": null, "ForcedSpawn": null, "Privileges": [ "chat" ], "RuntimePrivileges": [], "DefaultGameMode": 2, "Color": "DarkGray", "LandClaimAllowance": 0, "LandClaimMinSize": { "X": 5, "Y": 5, "Z": 5 }, "LandClaimMaxAreas": 3, "AutoGrant": false }, { "Code": "limitedsuplayer", "PrivilegeLevel": -1, "Name": "Limited Survival Player", "Description": "Can use/place/break blocks only in permitted areas (priv level -1), create/manage player groups and chat", "DefaultSpawn": null, "ForcedSpawn": null, "Privileges": [ "controlplayergroups", "manageplayergroups", "chat", "build", "useblock", "attackcreatures", "attackplayers", "selfkill" ], "RuntimePrivileges": [], "DefaultGameMode": 1, "Color": "White", "LandClaimAllowance": 0, "LandClaimMinSize": { "X": 5, "Y": 5, "Z": 5 }, "LandClaimMaxAreas": 3, "AutoGrant": false }, { "Code": "limitedcrplayer", "PrivilegeLevel": -1, "Name": "Limited Creative Player", "Description": "Can use/place/break blocks in only in permitted areas (priv level -1), create/manage player groups, chat, fly and set his own game mode (= allows fly and change of move speed)", "DefaultSpawn": null, "ForcedSpawn": null, "Privileges": [ "controlplayergroups", "manageplayergroups", "chat", "build", "useblock", "gamemode", "freemove", "attackcreatures", "attackplayers", "selfkill" ], "RuntimePrivileges": [], "DefaultGameMode": 2, "Color": "LightGreen", "LandClaimAllowance": 0, "LandClaimMinSize": { "X": 5, "Y": 5, "Z": 5 }, "LandClaimMaxAreas": 3, "AutoGrant": false }, { "Code": "suplayer", "PrivilegeLevel": 0, "Name": "Survival Player", "Description": "Can use/place/break blocks in unprotected areas (priv level 0), create/manage player groups and chat. Can claim an area of up to 8 chunks.", "DefaultSpawn": null, "ForcedSpawn": null, "Privileges": [ "controlplayergroups", "manageplayergroups", "chat", "areamodify", "build", "useblock", "attackcreatures", "attackplayers", "selfkill" ], "RuntimePrivileges": [], "DefaultGameMode": 1, "Color": "White", "LandClaimAllowance": 262144, "LandClaimMinSize": { "X": 5, "Y": 5, "Z": 5 }, "LandClaimMaxAreas": 3, "AutoGrant": false }, { "Code": "crplayer", "PrivilegeLevel": 100, "Name": "Creative Player", "Description": "Can use/place/break blocks in all areas (priv level 100), create/manage player groups, chat, fly and set his own game mode (= allows fly and change of move speed). Can claim an area of up to 40 chunks.", "DefaultSpawn": null, "ForcedSpawn": null, "Privileges": [ "controlplayergroups", "manageplayergroups", "chat", "areamodify", "build", "useblock", "gamemode", "freemove", "attackcreatures", "attackplayers", "selfkill" ], "RuntimePrivileges": [], "DefaultGameMode": 2, "Color": "LightGreen", "LandClaimAllowance": 1310720, "LandClaimMinSize": { "X": 5, "Y": 5, "Z": 5 }, "LandClaimMaxAreas": 6, "AutoGrant": false }, { "Code": "sumod", "PrivilegeLevel": 200, "Name": "Survival Moderator", "Description": "Can use/place/break blocks everywhere (priv level 200), create/manage own/other player groups, chat, kick/ban players and do serverwide announcements. Can claim an area of up to 4 chunks.", "DefaultSpawn": null, "ForcedSpawn": null, "Privileges": [ "controlplayergroups", "manageplayergroups", "manageotherplayergroups", "chat", "areamodify", "build", "useblock", "buildblockseverywhere", "useblockseverywhere", "kick", "ban", "announce", "readlists", "attackcreatures", "attackplayers", "selfkill" ], "RuntimePrivileges": [], "DefaultGameMode": 1, "Color": "Cyan", "LandClaimAllowance": 1310720, "LandClaimMinSize": { "X": 5, "Y": 5, "Z": 5 }, "LandClaimMaxAreas": 60, "AutoGrant": false }, { "Code": "crmod", "PrivilegeLevel": 500, "Name": "Creative Moderator", "Description": "Can use/place/break blocks everywhere (priv level 500), create/manage own/other player groups, chat, kick/ban players, fly and set his own or other players game modes (= allows fly and change of move speed). Can claim an area of up to 40 chunks.", "DefaultSpawn": null, "ForcedSpawn": null, "Privileges": [ "controlplayergroups", "manageplayergroups", "manageotherplayergroups", "chat", "areamodify", "build", "useblock", "buildblockseverywhere", "useblockseverywhere", "kick", "ban", "gamemode", "freemove", "commandplayer", "announce", "readlists", "attackcreatures", "attackplayers", "selfkill" ], "RuntimePrivileges": [], "DefaultGameMode": 2, "Color": "Cyan", "LandClaimAllowance": 1310720, "LandClaimMinSize": { "X": 5, "Y": 5, "Z": 5 }, "LandClaimMaxAreas": 60, "AutoGrant": false }, { "Code": "admin", "PrivilegeLevel": 99999, "Name": "Admin", "Description": "Has all privileges, including giving other players admin status.", "DefaultSpawn": null, "ForcedSpawn": null, "Privileges": [ "build", "useblock", "buildblockseverywhere", "useblockseverywhere", "attackplayers", "attackcreatures", "freemove", "gamemode", "pickingrange", "chat", "kick", "ban", "whitelist", "setwelcome", "announce", "readlists", "give", "areamodify", "setspawn", "controlserver", "tp", "time", "grantrevoke", "root", "commandplayer", "controlplayergroups", "manageplayergroups", "selfkill", "manageotherplayergroups", "worldedit" ], "RuntimePrivileges": [], "DefaultGameMode": 1, "Color": "LightBlue", "LandClaimAllowance": 2147483647, "LandClaimMinSize": { "X": 5, "Y": 5, "Z": 5 }, "LandClaimMaxAreas": 99999, "AutoGrant": true } ], "DefaultRoleCode": "suplayer", "ModPaths": [ "Mods", "/home" ], "AntiAbuse": 0, "WorldConfig": { "Seed": "1821141230", "SaveFileLocation": "/home/vsserver", "WorldName": "Awesome Village Lands", "AllowCreativeMode": true, "PlayStyle": "surviveandbuild", "PlayStyleLangCode": "preset-surviveandbuild", "WorldType": "standard", "WorldConfiguration": { "gameMode": "survival", "playerlives": "-1", "startingClimate": "temperate", "spawnRadius": "50", "graceTimer": "0", "deathPunishment": "keep", "droppedItemsTimer": "600", "seasons": "enabled", "daysPerMonth": "9", "harshWinters": "true", "blockGravity": "sandgravel", "caveIns": "off", "allowFallingBlocks": true, "allowFireSpread": true, "lightningFires": false, "allowUndergroundFarming": false, "noLiquidSourceTransport": false, "playerHealthPoints": "15", "playerHealthRegenSpeed": "1", "playerHungerSpeed": "1", "lungCapacity": "40000", "bodyTemperatureResistance": "0", "playerMoveSpeed": "1.5", "creatureHostility": "aggressive", "creatureStrength": "1", "creatureSwimSpeed": "2", "foodSpoilSpeed": "1", "saplingGrowthRate": "1", "toolDurability": "1", "toolMiningSpeed": "1", "propickNodeSearchRadius": "6", "microblockChiseling": "stonewood", "allowCoordinateHud": true, "allowMap": true, "colorAccurateWorldmap": false, "loreContent": true, "clutterObtainable": "ifrepaired", "temporalStability": true, "temporalStorms": "sometimes", "tempstormDurationMul": "1", "temporalRifts": "visible", "temporalGearRespawnUses": "20", "temporalStormSleeping": "0", "worldClimate": "realistic", "landcover": "0.975", "oceanscale": "5", "upheavelCommonness": "0.5", "geologicActivity": "0.05", "landformScale": "1.0", "worldWidth": "1024000", "worldLength": "1024000", "worldEdge": "traversable", "polarEquatorDistance": "100000", "storyStructuresDistScaling": "1", "globalTemperature": "1", "globalPrecipitation": "1", "globalForestation": "0", "globalDepositSpawnRate": "1", "surfaceCopperDeposits": "0.12", "surfaceTinDeposits": "0.007", "snowAccum": "true", "allowLandClaiming": true, "classExclusiveRecipes": true, "auctionHouse": true }, "MapSizeY": 256, "CreatedByPlayerName": "bughazard", "DisabledMods": [], "RepairMode": false }, "NextPlayerGroupUid": 10, "GroupChatHistorySize": 20, "MaxOwnedGroupChannelsPerUser": 10, "OnlyWhitelisted": false, "WhitelistMode": 0, "VerifyPlayerAuth": true, "DefaultSpawn": null, "AllowPvP": true, "AllowFireSpread": true, "AllowFallingBlocks": true, "HostedMode": false, "HostedModeAllowMods": false, "VhIdentifier": null, "StartupCommands": null, "RepairMode": false, "AnalyzeMode": false, "CorruptionProtection": true, "RegenerateCorruptChunks": false, "ChatRateLimitMs": 1000, "DieBelowDiskSpaceMb": 400, "ModIdBlackList": null, "ModIdWhiteList": null, "ServerIdentifier": "d31ba0e7-8c5e-4f15-bce4-f42d692c0d22", "LogBlockBreakPlace": false, "LogFileSplitAfterLine": 500000, "DieAboveErrorCount": 100000, "LoginFloodProtection": false, "TemporaryIpBlockList": false, "DisableModSafetyCheck": false, "DieAboveMemoryUsageMb": 50000 }
Fat_Lizardman Posted January 26 Report Posted January 26 Hey! I just made a fork of your project and added this mod to auto install https://mods.vintagestory.at/vintagercon so that the server has a means of remote communications, i also added ttyd to handle the exposure of the rcon server so now the console is accessible via http. check it out! https://github.com/JoshEvans-Weber/casaos-store/tree/ff130cc42fe8a93582401eb1e16af357f5bc41c1/Apps/vintagestory-custom this container also has been put into a repository that is accessible via CasaOS's appstore using the instructions in the readme.md
mohmaniac Posted February 1 Report Posted February 1 Hey @Drahkar! very cool and easy way for spawning a vs server from scratch, thank you! I'm struggling with connecting to the server due to 'This server only allows whitelisted players to join. You are not on the whitelist.' I set the VS_CFG_ONLY_WHITELISTED env variable to false - but sill didn't work. This changes the OnlyWhitelisted setting in the server config, but that seems to be deprecated? As stated here the whitelist behaviour can be changed by setting WhitelistMode to 1 (off) or 2 (on). I was unable to double-check if this will fix the issue (just started some readonly remote container without persistent volumes), but sounds conclusive to me.... Best Regards, mohmaniac
Drahkar Posted February 7 Author Report Posted February 7 @mohmaniac, Thank you for the note. Also @Fat_Lizardman, thank you as well. I'm going to look into making the adjustments to address the whitelisting (I ran into that as well, but forgot about it since I just manually modified the config file after provisioning.) I'll look into the RCon mod, and what adjustments need to happen for fixing whitelisting management. If someone was willing to open Github Issues for each item on the Repository, that would be really helpful! I'm going to get 1.22.0-pre.1 available for those who want to test against it as well.
Drahkar Posted February 9 Author Report Posted February 9 On 2/7/2026 at 8:44 AM, Drahkar said: @mohmaniac, Thank you for the note. Also @Fat_Lizardman, thank you as well. I'm going to look into making the adjustments to address the whitelisting (I ran into that as well, but forgot about it since I just manually modified the config file after provisioning.) I'll look into the RCon mod, and what adjustments need to happen for fixing whitelisting management. If someone was willing to open Github Issues for each item on the Repository, that would be really helpful! I'm going to get 1.22.0-pre.1 available for those who want to test against it as well. I'm almost done with the new image. Taking the advice, I have incorporated RCon, but I've also added a number of other features to make life running the server less painful, which includes a packaged RCon Web Client. I hope to have everything finished, tested and ready this week.
Drahkar Posted February 15 Author Report Posted February 15 I'm in the process of final testing for the new release. Once that is done, I'll be updating the documentation to make sure it reflects the current state. Hope everyone is having a good weekend.
Drahkar Posted February 18 Author Report Posted February 18 The new image and latest tag have been published. It has some improvements and features added to it. The main post has been updated with details, but a summary of changes are below. Summary of Changes (v0.0.28 → v0.0.30) Feature Changes Automated Mod Installation Automatic installation and configuration of Vintage-RCON mod Enabled via VS_RCON_ENABLED environment variable (Default: true) Built-in RCon Web Client for remote console access Single-user authentication support OAuth integration (Google, GitHub, Facebook, Apple) Fixed whitelist enforcement feature Replaced VS_CFG_ONLY_WHITELISTED with VS_CFG_ENFORCE_WHITELIST New Environment Variables RCon Configuration: VS_INSTALL_RCON - Enable/disable RCon mod installation VS_RCON_PASSWORD - RCon authentication password VS_RCON_WEB_PORT - Web client port (default: 8080) VS_RCON_WEB_SECRET - JWT secret key for web client VS_RCON_WEB_USERNAME - Traditional login username VS_RCON_WEB_PASSWORD - Traditional login password OAuth Configuration: VS_RCON_WEB_OAUTH_ENABLED - Enable OAuth authentication VS_RCON_WEB_OAUTH_EMAILS - Comma-separated authorized email list VS_RCON_WEB_OAUTH_GOOGLE_* - Google OAuth credentials VS_RCON_WEB_OAUTH_FACEBOOK_* - Facebook OAuth credentials VS_RCON_WEB_OAUTH_GITHUB_* - GitHub OAuth credentials VS_RCON_WEB_OAUTH_APPLE_* - Apple OAuth credentials Updated Variables: VS_CFG_ENFORCE_WHITELIST - Replaces VS_CFG_ONLY_WHITELISTED
Josh Oxborrow Posted February 20 Report Posted February 20 (edited) Cleared because I was being dumb. See my post below on getting whitelisted. Edited February 20 by Josh Oxborrow removing everything since I was just being dumb. This would just confuse others.
Drahkar Posted February 20 Author Report Posted February 20 12 hours ago, Josh Oxborrow said: This is the error I get in game but I have changed the whitelistmode to 1 and when I rerun server/server.sh status I get root@c4ee3890c924:/vintagestory# server/server.sh status Data path is /vintagestory/data VintagestoryServer.dll is not running. @Josh Oxborrow - This looks like you are trying to start up the server manually inside of the container? I'm asking because the questions about commands are all about actions that are managed entirely within the container and don't require user interaction. Can you clarify the steps you are following for getting things running?
Josh Oxborrow Posted February 20 Report Posted February 20 (edited) Oh my god. that was a trip. So I discovered what I did wrong here and will explain it simply for everyone else trying. So once you launch the docker image you need to console in using root@docker:/vintagestory# docker container exec -it vintagestory-server /bin/bash Then I install nano because I hate VIM apt-get update && apt-get install nano Then navigate to the data folder cd data and open the serverconfig.json nano serverconfig.json near the bottom you can change the whitelist mode to 1 to get out of Nano use ctrl+x then y to say yes you want to save and then enter then exit to docker and restart the server and it should work. I made a lot of mistakes but one that was causing the biggest headache was I also tried to add my name to the whitelist but didn't use the right syntax so the server was rebooting over and over again. Edited February 20 by Josh Oxborrow
Drahkar Posted February 21 Author Report Posted February 21 4 hours ago, Josh Oxborrow said: nano serverconfig.json near the bottom you can change the whitelist mode to 1 to get out of Nano use ctrl+x then y to say yes you want to save and then enter then exit to docker and restart the server and it should work. I made a lot of mistakes but one that was causing the biggest headache was I also tried to add my name to the whitelist but didn't use the right syntax so the server was rebooting over and over again. The newest version of the image that was just released resolves this issue. You can just set VS_CFG_ENFORCE_WHITELIST to true and it will take care of it. I also updated the Server Config wiki entry, to clarify one does nothing and the other actually sets it. Sorry you were hit by this gap of information as well. It was definitely a headache. 1
Fat_Lizardman Posted February 22 Report Posted February 22 On 2/7/2026 at 7:44 AM, Drahkar said: @mohmaniac, Thank you for the note. Also @Fat_Lizardman, thank you as well. I'm going to look into making the adjustments to address the whitelisting (I ran into that as well, but forgot about it since I just manually modified the config file after provisioning.) I'll look into the RCon mod, and what adjustments need to happen for fixing whitelisting management. If someone was willing to open Github Issues for each item on the Repository, that would be really helpful! I'm going to get 1.22.0-pre.1 available for those who want to test against it as well. If you checkout my CasaOS appstore i actually have all test versions for 1.22 available as versions so to download 1.22.0-pre.3 you just put that in as the version of the container you want https://github.com/JoshEvans-Weber/casaos-store/archive/refs/heads/main.zip
Drahkar Posted February 23 Author Report Posted February 23 18 hours ago, Fat_Lizardman said: If you checkout my CasaOS appstore i actually have all test versions for 1.22 available as versions so to download 1.22.0-pre.3 you just put that in as the version of the container you want https://github.com/JoshEvans-Weber/casaos-store/archive/refs/heads/main.zip I appreciate your interest and what you've started. Anything that makes these games easier for people is a really good thing, in my opinion. I'll plan to continue working with developing this image and pipeline. It was originally primarily for myself, but with so many people who had been struggling with the server and asking about a Docker container, I decided to make it available for everyone and source ideas on improvements from those using it. As you continue working on those implementation, I would suggest creating a thread specifically for it. "Vintage Story Dedicated Server CasaOS Appstore" for example. Primarily because I won't do support on tooling and installs developed by someone else. Have a good one!
Varusal Posted February 24 Report Posted February 24 First of all, awesome work @Drahkar Makes setting up a server a breeze! --- Now, I also have issues with the whitelisting. Here is my docker compose.yaml version: '3.8' services: vintagestory-server: image: ghcr.io/darkmatterproductions/vintagestory:latest container_name: vintagestory-server ports: - "42420:42420/tcp" - "42420:42420/udp" volumes: - /opt/vintagestory:/vintagestory/data environment: - ENABLE_DEBUG_LOGGING=false - ENABLE_CHAT_LOGGING=true - VS_CFG_SERVER_NAME=My Vintage Story Server - VS_CFG_MAX_CLIENTS=16 - VS_CFG_ENFORCE_WHITELIST=0 restart: unless-stopped VS_CFG_ENFORCE_WHITELIST should be set to false (0) which means no whitelist will be used, right? Also tried (just for testing), the values "1","2" and "false". None seem to work. But sadly, there is still the "not in whitelist" issue.
Drahkar Posted February 25 Author Report Posted February 25 @Varusal - I'm glad it helps. It was a huge pain for me when I first started with things, not having a fast way to start with a server. Glad I can play a part to help other with this. In regards to the situation you are working with. I need to confirm one thing. When you go to start the sever back up, does /opt/vintagestory still have the original contents from when you first started and were having the errors. The reason I ask is that if it does, then you are having a problem because the configuration already has the settings in place. If the serverconfig.json file already exists, then it doesn't change anything in place. I do this, to ensure that your configuration doesn't get inadvertently overwritten. You can do a one time run with the environment variable FORCE_REGENERATE_CONFIG set to true which will force it to generate the configuration again, using your updated settings. 1
Varusal Posted February 27 Report Posted February 27 On 2/25/2026 at 10:01 PM, Drahkar said: @Varusal - I'm glad it helps. It was a huge pain for me when I first started with things, not having a fast way to start with a server. Glad I can play a part to help other with this. In regards to the situation you are working with. I need to confirm one thing. When you go to start the sever back up, does /opt/vintagestory still have the original contents from when you first started and were having the errors. The reason I ask is that if it does, then you are having a problem because the configuration already has the settings in place. If the serverconfig.json file already exists, then it doesn't change anything in place. I do this, to ensure that your configuration doesn't get inadvertently overwritten. You can do a one time run with the environment variable FORCE_REGENERATE_CONFIG set to true which will force it to generate the configuration again, using your updated settings. Well actually this was it! I removed the config restarted the server and it worked! Thank you very much
Drahkar Posted February 28 Author Report Posted February 28 5 hours ago, Varusal said: Well actually this was it! I removed the config restarted the server and it worked! Thank you very much Wonderful! Glad I could help! 1
Shijikori Posted March 5 Report Posted March 5 (edited) Hey! Just letting you know I updated Vintage RCON to fix an issue with packet handling. Please make sure that your web console is compatible with the classic handling that was reimplemented in the new version! I overlooked this when I checked the changes submitted by Taehan. Every command packet should now receive only one packet of response. Please ensure that your console sends a SERVERDATA_RESPONSE_VALUE (packet type 0) after receiving the first response to a command. The server should respond with an empty serverdata response packet if there are no more chunks left to the response. Feel free to communicate with me through Discord (@shijikori) if you need technical details Refer to Valve's documentation to validate your rcon web console's client behaviour : https://developer.valvesoftware.com/wiki/Source_RCON_Protocol Edited March 5 by Shijikori 1
Recommended Posts