Skip to content

Commit 979438b

Browse files
dooly123dooly123
authored
Merge pull request #95 from Toys0125/Adding-Headless-Docker-compose
Fix correct path in the linux yaml.
2 parents 5c42425 + 0bef5fe commit 979438b

1 file changed

Lines changed: 74 additions & 27 deletions

File tree

‎content/docs/server/headless.mdx‎

Lines changed: 74 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,8 @@ title: Headless Clients
33
---
44

55
import { Callout } from 'fumadocs-ui/components/callout';
6+
import { Step, Steps } from 'fumadocs-ui/components/steps';
7+
68

79
## Introduction
810

@@ -25,11 +27,15 @@ This page focuses on running the headless client itself. For the server-side set
2527

2628
You have two main ways to run headless clients:
2729

28-
- Download the Linux or Windows headless client build from the GitHub artifacts
30+
- Download the Linux or Windows headless client build from the [GitHub artifacts](https://nightly.link/BasisVR/Basis/workflows/build-docker-server/developer?preview)
2931
- Run the published headless Docker images
3032

3133
Docker is useful when you want repeatable containerized setups or need to scale many instances quickly. If you only need to run one or a few headless clients, downloading the platform build directly is also valid.
3234

35+
<Callout type="warn">
36+
By default the Windows Version of the headless is built with Mono instead of IL2CPP and is a limitation of the UnityCI for building. Mono uses about 1.5-2x more memory than IL2CPP so use the linux version unless package states its IL2CPP version.
37+
</Callout>
38+
3339
## Before You Start
3440

3541
Make sure the server you want to target is already reachable.
@@ -40,36 +46,74 @@ Make sure the server you want to target is already reachable.
4046

4147
The server documentation also notes that `config.xml` values can be overridden by environment variables. That matters here because the same pattern is used for the headless client examples below.
4248

43-
## Docker Compose Configuration
49+
## Setting up Desktop Docker
50+
<Steps>
51+
<Step>
52+
Open `System Information` and check if Virtualization-based security says `Running` and Virtualization-based security Available has:`Security Properties Base Virtualization Support`
53+
54+
If not go into your bios and Enable AMD-Vi or Intel VT-d based on your CPU.
55+
56+
Google your motherboard that under `BaseBoard Product` to found out where the setting is and what key to open bios.
57+
</Step>
58+
<Step>
59+
Go to [Docker and Download for Windows](https://docs.docker.com/desktop/setup/install/windows-install/) and install Docker Desktop.
60+
</Step>
61+
<Step>
62+
Make a folder for the `docker-compose.yml` and copy the example below.
63+
</Step>
64+
<Step>
65+
Start a Command Prompt or Powershell in that directory. When using file explorer you can launch Command Prompt by typing `cmd.exe` in the url bar or explorer.
66+
</Step>
67+
<Step>
68+
Type the command `docker compose up -d` to start the containers
69+
</Step>
70+
<Step>
71+
Use `docker ps` to see the health of all containers and wait until all say healthy. Should take about 30 seconds to a minute.
72+
</Step>
73+
<Step>
74+
Use `docker compose scale "basis-headless=#` to increase the number of containers. Than go back to a step and repeat until either you out of CPU or RAM.
75+
76+
*Replace `#` with a number in increments of 5*
77+
78+
<Callout type="info">
79+
You can also measure usage with `docker compose stats`
80+
</Callout>
81+
</Step>
82+
</Steps>
4483

45-
When running Docker from Docker Desktop, Docker normally uses WSL2 under the hood, so the Linux image is usually the correct choice there. If you are specifically running Windows containers, use the Windows image instead.
84+
## Docker Compose Configuration
4685

47-
### Linux
86+
When running Docker from Docker Desktop, Docker engine normally uses WSL2 under the hood, so the Linux image is usually the correct choice there. If you are specifically running Windows containers *for example Windows Server 2016*, use the Windows image instead found in the Basis-Headless package on github.
4887

49-
```yml
50-
services:
51-
basis-headless:
52-
image: ghcr.io/basisvr/basis-headless:nightly-linux
53-
environment:
54-
Port: 4296
55-
Password: default_password
56-
Ip: 'server1.basisvr.org'
57-
volumes:
58-
- ./config.xml:/HeadlessLinuxServer_Data/config.xml
59-
```
88+
<Callout type="warn">
89+
By Default use the linux version of the docker image as its built using IL2CPP and if you get manifest errors about linux, you need to use the `-linux` versions.
90+
</Callout>
6091

61-
### Windows
92+
### docker-compose.yml
6293

6394
```yml
6495
services:
6596
basis-headless:
66-
image: ghcr.io/basisvr/basis-headless:nightly-windows
97+
image: ghcr.io/basisvr/basis-headless:nightly-linux
98+
scale: 3 # You should change based on how much RAM you have. 1.5GB per instance is normally required.
6799
environment:
68100
Port: 4296
69101
Password: default_password
70102
Ip: 'server1.basisvr.org'
103+
HealthCheckEnabled: "true"
104+
HealthCheckHost: "0.0.0.0"
105+
HealthCheckPort: 10666
106+
HealthPath: "/health"
71107
volumes:
72-
- ./config.xml:/app/HeadlessWindowsServer_Data/config.xml
108+
- ./Basis:/root/.config/unity3d/Basis Unity/Basis Unity # For Sharing Cached files. Optional not required
109+
- "${APPDATA}/../LocalLow/Basis Unity/Basis Unity:/root/.config/unity3d/Basis Unity/Basis Unity" #If you want to use your own cache and avatar files. *Corruption possible
110+
- ./config.xml:/app/HeadlessLinuxServer_Data/config.xml # Optional will be overridden when using environment variables
111+
healthcheck:
112+
test: ["CMD-SHELL","bash -lc 'exec 3<>/dev/tcp/127.0.0.1/10666 && printf \"GET /health HTTP/1.1\r\nHost: localhost\r\nConnection: close\r\n\r\n\" >&3 && grep -q \"200\" <&3`"]
113+
interval: 30s
114+
timeout: 5s
115+
retries: 3
116+
start_period: 20s
73117
```
74118
75119
## What the Settings Mean
@@ -81,6 +125,10 @@ The examples above use the minimum values needed to connect:
81125
| `IP` | Hostname or IP address of the Basis server |
82126
| `Port` | UDP port the server listens on, usually `4296` |
83127
| `Password` | Server password required to join |
128+
| `HealthCheckEnabled` | Enable or Disable HealthCheckEndpoint |
129+
| `HealthCheckHost` | Ip Endpoint listens on |
130+
| `HealthCheckPort` | Port Endpoint listens on |
131+
| `HealthPath` | Path for Health info |
84132

85133
If you mount a `config.xml`, treat it as the file-based fallback configuration. If you also set environment variables, the docs for the main server note that environment values override xml values, so keep one source of truth where possible to avoid confusion during testing.
86134

@@ -89,24 +137,23 @@ If you mount a `config.xml`, treat it as the file-based fallback configuration.
89137

90138
Docker Compose can launch multiple headless clients from the same service definition:
91139

92-
### `docker compose -f docker-compose.yml up -d --scale "basis-headless=10"`
140+
<h3> `docker compose --scale "basis-headless=10"`</h3> *--scale when not set in the docker-compose.yml*
93141

94142
As a rough guideline, the existing note recommends budgeting about `1.5 GB` of memory per instance. For example, if you have around `30 GB` available, you can plan on roughly `20` instances.
95143

144+
<Callout type="warning" title="Load few at a time">
145+
Do not try launching all clients at once. You will overload your computers ram, and at the current moment we don't offer a script that provides easy launching of instance.
146+
147+
Best way is to wait until the health status of all launched containers are showing healthy before adding more.
148+
</Callout>
149+
96150
This is only a starting estimate. Actual limits depend on:
97151

98152
- Available RAM
99153
- CPU cores
100154
- The server's `PeerLimit`
101155
- Bandwidth available between the headless clients and the server
102156

103-
## Suggested Load Testing Workflow
104-
105-
1. Start the Basis server and confirm it is listening.
106-
2. Check the server health endpoint at `http://localhost:10666/health` or the equivalent host for your deployment.
107-
3. Launch a small number of headless clients first.
108-
4. Verify they can connect with the expected `IP`, `Port`, and `Password`.
109-
5. Increase the scale gradually and watch server health, bandwidth, and machine resource usage.
110157

111158
## Monitoring During Tests
112159

@@ -141,7 +188,7 @@ The server docs explicitly note that client and server code must agree on the se
141188

142189
If the headless clients do not connect, check these first:
143190

144-
- The server address in `IP` is reachable from the container
191+
- The server address in `Ip` is reachable from the container
145192
- The server password matches
146193
- `4296/udp` is open and mapped correctly
147194
- You are using the correct image for your container runtime

0 commit comments

Comments
 (0)