I didn't know that there was another docker vintagestory server, but I didn't see that until I made this one. Mine focuses on docker compose and has a preset config for hosting behind CGNAT. I wasn't sure about posting the image to dockerhub or a release page, because vintage story is proprietary. Instead you'll have to put in the server download link in a .env file. After that docker compuse up -d takes care of the rest.
The repo is at: https://codeberg.org/Shampan/vintagestory-server-docker
# Vintage Story Server (Docker)
A containerized Vintage Story server with simple setup using Docker Compose.
---
## Prerequisites
- Docker (v20.10 or higher)
- Docker Compose (v2.0 or higher)
- A Vintage Story server download link from your account at https://account.vintagestory.at/downloads
**Note:** If you are behind CGNAT or don't have a public IP, see [Tunneling Solution](#tunneling-solution-for-cgnat-or-no-public-ip).
---
## Features
- **Simple deployment** - Build and run with a single command
- **Data persistence** - Server saves and configuration stored in a local `./data` directory
- **Interactive mode** - Attach to the running container to send commands directly
- **Auto-restart** - Server automatically restarts if it crashes
- **Customizable** - Use any Vintage Story server version by changing the download URL
---
## First Time Setup
### Creating your `.env` file
The `.env` file stores your server configuration. Copy the example file:
```bash
cp .env.example .env
```
Then edit it with your actual server URL:
```bash
nano .env # or use your preferred editor
```
**Required format:**
```
VS_SERVER_URL=https://your-download-link-here.tar.gz
```
**Where to get the URL:**
1. Log in at https://account.vintagestory.at/downloads
2. Click "Show all available downloads and mirrors of Vintage Story"
3. Click Find the newest link that says "Linux tar.gz Archive (server only)
4. Right click on the link, then select "Copy link".
5. Copy the full URL into your `.env` file
### Starting your server
Once `.env` is configured:
```bash
# Build and start in one command
docker compose up -d
# Check it's running
docker compose ps
# View logs
docker compose logs -f
```
### Access the Server console
```bash
docker compose attach vintagestory
```
Press `Ctrl+P`, then `Ctrl+Q` to detach without stopping.
### Stopping and removing
```bash
# Stop the server
docker compose stop
# Remove the container (data persists in ./data)
docker compose down
```
---
## Configuration
### Volume Mount
The `./data` directory on your host machine is mounted to `/data` inside the container. This directory contains:
- Server configuration files (`serverconfig.json`, etc.)
- World saves
- Player data
- Logs
**To backup your server:** Simply copy the `./data` directory.
### Port Mapping
- **Host Port:** 42420
- **Container Port:** 42420
The server is accessible to players on `your-server-ip:42420`.
**To change the port:** Edit `docker-compose.yaml` and modify the port mapping:
```yaml
ports:
- "YOUR_HOST_PORT:42420"
```
### Server Arguments
You can pass additional arguments to the server by modifying the `docker-compose.yaml`:
```yaml
services:
vintagestory:
command: ["--dataPath", "/data", "--port", "42420", "--maxPlayers", "20"]
```
---
## .NET Version
This container uses **.NET 8.0** (base image: `mcr.microsoft.com/dotnet/aspnet:8.0`).
Vintage Story server versions require specific .NET versions to run. The current container is configured for server versions that support .NET 8.0. If you want to use an older Vintage Story server version that requires a different .NET version, you'll need to update the base image in the `Dockerfile`.
**To change the .NET version:**
1. Open `Dockerfile`
2. Change the first line from `FROM mcr.microsoft.com/dotnet/aspnet:8.0` to your desired version (e.g., `mcr.microsoft.com/dotnet/aspnet:7.0`)
3. Rebuild the container: `docker compose build`
---
## Usage
### Viewing Logs
```bash
# View all logs
docker compose logs
# View logs in real-time
docker compose logs -f
# View last 100 lines
docker compose logs --tail=100
```
### Attaching to the Server Console
```bash
docker compose attach vintagestory
```
Once attached, you can:
- View server logs in real-time
- Send commands directly to the server
- See player join/leave messages
- Monitor server performance
**Detaching:** Press `Ctrl+P`, then `Ctrl+Q` (this detaches without stopping the server)
### Restarting the Server
```bash
docker compose restart
```
---
## Common Server Commands
All server commands can be found on the [Vintage Story Wiki](https://wiki.vintagestory.at/index.php?title=List_of_server_commands), but here are few helpful ones to get started.
```
/player [playername] whitelist on
/op [playername]
```
---
## Updating the Server
### Updating to a new version
**Method 1: Using `.env` (Recommended)**
1. Stop the server:
```bash
docker compose stop
```
2. Update the URL in `.env`:
```bash
nano .env
# Replace VS_SERVER_URL with new version link
```
3. Rebuild and restart:
```bash
docker compose build
docker compose up -d
```
**Method 2: Override at build time (Advanced)**
```bash
docker compose build --build-arg VS_SERVER_URL=https://new-url.tar.gz
docker compose up -d
```
This is useful for one-time builds without modifying `.env`.
---
## Troubleshooting
### Server won't start
**Check logs:**
```bash
docker compose logs
```
**Common issues:**
- Port 42420 already in use - change the port in `docker-compose.yaml`
- Insufficient disk space - ensure you have space for server data
- Invalid download URL - verify the URL is accessible
```bash
curl -I -f --connect-timeout 10 https://your-download-link.tar.gz
```
Output should be something like `HTTP/2 200` for the first line returned.
### Can't connect to server
**Verify server is running:**
```bash
docker compose ps
```
**Check port mapping:**
```bash
docker compose port vintagestory 42420
```
**Firewall:** Ensure port 42420 is open on your firewall:
```bash
sudo ufw allow 42420/tcp #Or whatever firewall tool you prefer
```
**Ports**
If you are using your router's public IP, make sure you've followed the proper [port forwarding](https://en.wikipedia.org/wiki/Port_forwarding) instructions for your specific router.
### Server crashes unexpectedly
**Check health status:**
```bash
docker inspect --format='{{.State.Health.Status}}' vintagestory-server
```
**View crash logs:**
```bash
docker compose logs --tail=200
```
**Increase restart delay:**
Edit `docker-compose.yaml` to add restart delay:
```yaml
restart: unless-stopped
restart_policy:
maximum_retry_count: 3
delay: 10s
```
### Lost server data
**Check if data directory exists:**
```bash
ls -la ./data
```
**If data is missing:**
- Ensure the volume mount is correct in `docker-compose.yaml`
- Restore from backup if available
---
## Advanced Configuration
### Custom Server Configuration
Edit `serverconfig.json` in the `./data` directory, then restart the container.
### Running Multiple Servers
To run multiple servers on the same machine, create separate directories with different `docker-compose.yaml` files:
```
servers/
├── server1/
│ ├── docker-compose.yaml
│ └── data/
└── server2/
├── docker-compose.yaml
└── data/
```
Each with different port mappings:
```yaml
ports:
- "42421:42420" # Server 1
- "42422:42420" # Server 2
```
### Environment Variables
By default, Docker Compose automatically reads `.env` from the current directory (use the provided `.env.example` as a template). No extra flags needed!
If you need to use a custom env file:
```bash
docker compose --env-file /path/to/custom.env up -d
```
Or export variables in your shell:
```bash
export VS_SERVER_URL=https://your-url.tar.gz
docker compose up -d
```
---
## License
Vintage Story Server software is subject to the [Vintage Story Terms of Service](https://www.vintagestory.at/tos.html/).
This Docker configuration is licensed under the **GPL v3**. See [LICENSE](LICENSE) for details.
```
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see <https://www.gnu.org/licenses/>.
```
---
## Tunneling Solution (for CGNAT or No Public IP)
If you're behind CGNAT (Carrier-Grade NAT) or don't have a public IP address, you won't be able to forward ports on your router. This is common with mobile networks, fiber connections, or some ISP setups. In these cases, you can use **frp** (Fast Reverse Proxy) to create an outbound tunnel to a machine that *does* have a public IP (such as a VPS or friend's place with a public IP).
### What is frp?
[frp](https://github.com/fatedier/frp) is a high-performance reverse proxy that enables you to expose a local service to the internet through a tunnel. It consists of two components:
- **frps** (server) - Runs on a machine with a public IP
- **frpc** (client) - Runs on your private machine running the Vintage Story server
```
┌─────────────────┐
│ Internet │
└────────┬────────┘
│
│ Players connect here
│ public-ip:42420
▼
┌─────────────────────────┐
│ Public IP Machine │
│ (runs frps) │
│ Port 7000, 42420 open │
└───────────┬─────────────┘
│
│ frp tunnel (encrypted)
│ Port 7000
▼
┌─────────────────────────┐
│ Private Machine │
│ (runs frpc + VS Server)│
│ Port 42420 │
└─────────────────────────┘
```
### Download frp
Download the latest release from the [frp GitHub releases](https://github.com/fatedier/frp/releases).
For Linux (amd64):
```bash
# Example for v1.2.0 - check releases for latest version
wget https://github.com/fatedier/frp/releases/download/v1.2.0/frp_<verion_and_architecture>.tar.gz
tar -xzf frp_<version_and_architecture>.tar.gz
cd frp_<version_and_architecture>
```
You'll find the `frps` and `frpc` binaries in the extracted folder.
### Configuration Files
Two configuration files are provided in this repository:
| File | Purpose | Location |
|------|---------|----------|
| `frps.toml` | Server configuration | Machine with **public IP** |
| `frpc.toml` | Client configuration | Machine running **Vintage Story server** |
** Important: Before using, you must edit both files:**
1. **frps.toml** - Replace `INSERT_TOKEN_HERE` with a secure random token
2. **frpc.toml** - Replace `INSERT_TOKEN_HERE` with the **same token**, and change `serverAddr = "PUBLIC_IP"` to your public IP machine's address or domain
You can generate a secure token using [randomkeygen.com](https://randomkeygen.com) or similar tools.
### Port Forwarding (If Behind a Router)
If your public IP machine is itself behind a router or firewall, you must forward **both** ports:
- **7000** - frp control connection
- **42420** - Vintage Story game traffic
Without forwarding port 42420, players won't be able to connect.
### Quick Start
**On Public IP Machine (frps):**
```bash
# Edit frps.toml first!
./frps -c frps.toml
```
**On Vintage Story Server Machine (frpc):**
```bash
# Edit frpc.toml first!
./frpc -c frpc.toml
```
**For production use**, run with `nohup` or set up as a systemd service:
```bash
# Nohup example (runs in background)
nohup ./frps -c frps.toml > frps.log 2>&1 &
nohup ./frpc -c frpc.toml > frpc.log 2>&1 &
```
### Systemd Service (Optional)
For automatic startup and better management, create systemd services:
**On Public IP Machine (/etc/systemd/system/frps.service):**
```ini
[Unit]
Description=frp Server
After=network.target
[Service]
Type=simple
User=root
ExecStart=/path/to/frp/frps -c /path/to/frps.toml
Restart=on-failure
RestartSec=5s
[Install]
WantedBy=multi-user.target
```
**On Server Machine (/etc/systemd/system/frpc.service):**
```ini
[Unit]
Description=frp Client
After=network.target
[Service]
Type=simple
User=root
ExecStart=/path/to/frp/frpc -c /path/to/frpc.toml
Restart=on-failure
RestartSec=5s
[Install]
WantedBy=multi-user.target
```
Enable and start the services:
```bash
sudo systemctl daemon-reload
sudo systemctl enable frps # or frpc on client
sudo systemctl start frps # or frpc on client
```
### Connecting
Players connect to: **`your-public-ip:42420`**
The traffic tunnels through frp to your Vintage Story server on the private machine.
---
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## Support
If you encounter any issues or have questions, please open an issue on the repository.
