zsuatem/vintagestory repository overview

⁠About

Simple Docker image of Vintage Story Server for amd64, arm64 and arm v7 architectures.

Note: Version 1.18.8+ only supports AMD64 architecture. Official ARM builds were discontinued⁠ as .NET 8 provides built-in ARM support, but Vintage Story still requires native AMD64 libraries. Consider using x86 emulation (QEMU) on ARM devices for newer versions.

Security: This image runs as a non-root user by default for better security. Legacy installations running as root are automatically detected and supported for backward compatibility. Existing non-root installations that use a custom UID/GID should continue to pass PUID and PGID explicitly.

⁠Quick Start

Get started quickly with a single command:

docker run -d --name vintagestory \
    -p 42420:42420/tcp \
    -p 42420:42420/udp \
    -v ./data:/vintagestory/data \
    zsuatem/vintagestory:latest

Your server data will be stored in the ./data directory. Access the console with docker attach vintagestory (detach with Ctrl + P Q).

⁠Tags

• latest, stable - latest stable version
  • 1.16 - latest 1.16.x (stable) version e.g. (1.14, 1.15)
    • 1.16.4 - 1.16.4 (stable) version e.g. (1.14.10, 1.15.2)
• unstable - latest unstable version
  • 1.16.5-rc.1 - 1.16.5-rc.1 (preview, rc) version e.g. (v1.14.0-pre.11, v1.15.0-pre.8)

⁠How to use

⁠Simple run

Simple run with default settings (not recommended).

docker run --name vintagestory -d -it -p 42420:42420/tcp -p 42420:42420/udp zsuatem/vintagestory:latest

⁠Data folder

If you want to easily change some settings or add mods you can mount the data folder or what you need to folder/file on your server. the data folder is mounted to a randomly named volume by default.

The data folder contains:

.
|-- BackupSaves
|-- Backups
|-- Cache
|-- Logs
|-- Macros
|-- Mods
|-- Playerdata
|-- Saves
|-- WorldEdit
|-- serverconfig.json
`-- servermagicnumbers.json

If you do not want to mount any file or folder you can copy the file from the server to the container using docker cp e.g. docker cp ./serverconfig.json vintagestory:/vintagestory/data/serverconfig.json.

⁠Access to console

You can easily access the console using docker attach vintagestory where "vintagestory" is the container name. To detach, use the keyboard shortcut Ctrl + P Q.

⁠Run the server (docker run)

Run with the data folder mounted to a local directory (recommended):

docker run --name vintagestory -d -it \
    -p 42420:42420/tcp \
    -p 42420:42420/udp \
    -v ./data:/vintagestory/data \
    zsuatem/vintagestory:latest

Or using a named volume:

docker run --name vintagestory -d -it \
    -p 42420:42420/tcp \
    -p 42420:42420/udp \
    -v vsserverdata:/vintagestory/data \
    zsuatem/vintagestory:latest

⁠Run the server (docker compose)

Same as above but as docker-compose.yml.

docker-compose.yml file:

services:
    vintagestory:
        image: zsuatem/vintagestory:latest
        container_name: vintagestory
        restart: always
        ports:
            - 42420:42420/tcp
            - 42420:42420/udp
        volumes:
            - ./data:/vintagestory/data
        stdin_open: true
        tty: true
        # Optional: Set custom user/group IDs
        # environment:
        #   - PUID=1000
        #   - PGID=1000

⁠Environment Variables

Set these variables to match your host user/group IDs if you want to force a specific runtime user.

⁠User and Permissions

⁠Default Behavior (Recommended)

By default, the container runs as a non-root user with UID=1000 and GID=1000 for new installations.

docker run -d -p 42420:42420/tcp -p 42420:42420/udp -v vsserverdata:/vintagestory/data zsuatem/vintagestory:latest
# Runs as UID=1000, GID=1000 (non-root)

⁠Custom User/Group IDs

If you need to force specific user/group IDs on your host system (e.g., to avoid permission issues with bind mounts), you can set custom PUID and PGID explicitly:

docker run -d \
    -p 42420:42420/tcp \
    -p 42420:42420/udp \
    -v /path/to/data:/vintagestory/data \
    -e PUID=1500 \
    -e PGID=1500 \
    zsuatem/vintagestory:latest

Or in docker-compose:

services:
    vintagestory:
        image: zsuatem/vintagestory:latest
        environment:
            - PUID=1500
            - PGID=1500
        volumes:
            - /path/to/data:/vintagestory/data

⁠Backward Compatibility (Legacy Installations)

If you're upgrading from an older version that stored data as root, the container will automatically detect this and continue running as root for backward compatibility. You'll see a warning message suggesting migration to non-root for better security.

If you're upgrading an existing non-root installation that used a custom UID/GID, keep passing the same PUID and PGID values after the upgrade.

⁠Migration from Root to Non-Root

If you have an existing installation running as root and want to migrate to non-root:

⁠Option 1: On Host (Recommended)

Fix permissions on your host before upgrading:

# Find your data directory (check with docker volume inspect)
sudo chown -R 1000:1000 /var/lib/docker/volumes/vsserverdata/_data
# or for bind mount:
sudo chown -R 1000:1000 /path/to/your/data

# Then run with default settings
docker run -d -v vsserverdata:/vintagestory/data zsuatem/vintagestory:latest

⁠Option 2: Using Temporary Container

docker run --rm -v vsserverdata:/data ubuntu chown -R 1000:1000 /data
docker run -d -v vsserverdata:/vintagestory/data zsuatem/vintagestory:latest

⁠Option 3: Keep Running as Root (Not Recommended)

If you prefer to keep running as root:

docker run -d -e PUID=0 -e PGID=0 -v vsserverdata:/vintagestory/data zsuatem/vintagestory:latest

Note: This bypasses security improvements and is not recommended.

⁠Troubleshooting

⁠Permission Denied Errors

If you see permission errors when the container starts:

1. Check ownership mismatch warning in container logs:

   docker logs vintagestory
   

   Copy

2. Fix ownership on your host to match the user you want the container to run as:

   sudo chown -R 1000:1000 /path/to/your/data
   

   Copy

3. Or set PUID/PGID to match your existing data explicitly:

   # Find current ownership
   ls -ln /path/to/your/data
   # Set matching PUID/PGID
   docker run -e PUID=<uid> -e PGID=<gid> ...
   

   Copy

4. If this is an existing non-root installation with a custom UID/GID, keep passing the matching PUID / PGID values after upgrading.

⁠Old vsuser Startup Bug

If you see a startup error like this:

Running with PUID=1000 and PGID=1000

Starting server as vsuser (UID=1000, GID=1000)...

❌ ERROR: User 1000:1000 cannot write to /vintagestory/data!
   Current ownership: UID=1000 GID=1000

   Fix permissions on your host:
   sudo chown -R 1000:1000 /path/to/data
   Or set PUID/PGID to match existing data ownership.

then you're likely running an older broken image version.

That error could happen even when the data directory ownership was already correct, because the old image tried to switch to a hard-coded user named vsuser and failed on some base images.

Fix:

1. Pull the latest image again:

   docker pull zsuatem/vintagestory:latest
   

   Copy
2. Recreate the container with the updated image.
3. If your existing data uses a custom non-root UID/GID, keep passing the matching PUID and PGID values explicitly.

⁠Container Runs as Root (Security Warning)

If you see warnings about running as root, this means you have data from an older version. For better security, consider migrating to non-root as described in the Migration section⁠.

⁠Healthcheck Causing Restarts

The image includes a healthcheck that verifies the server process is running. If your server takes a long time to start or you experience unexpected restarts, you can disable the healthcheck in docker-compose:

services:
    vintagestory:
        # ... other config ...
        healthcheck:
            disable: true

Or in docker run:

docker run --no-healthcheck ...

⁠Useful Links

• Official game site: Vintage Story⁠
• GitHub repository: zsuatem/VintageStory-Docker⁠
• Issue tracker: GitHub Issues⁠
• Docker Hub: zsuatem/vintagestory⁠

⁠Issues

If you run into a bug with this image, you can open an issue on GitHub.

This is an unofficial image maintained on a best-effort basis, so responses and fixes may take time. Please include your image tag, container configuration, and relevant logs.