Skip to content

Commit 1da3ed1

Browse files
madkodingmadkoding
committed
docs(readme): rewrite setup guide with platform-specific run modes
1 parent 23698da commit 1da3ed1

1 file changed

Lines changed: 94 additions & 77 deletions

File tree

‎README.md‎

Lines changed: 94 additions & 77 deletions
Original file line numberDiff line numberDiff line change
@@ -1,122 +1,139 @@
1-
# 🦾 SlimeVR Server + Web GUI in Docker
2-
3-
![Stars](https://img.shields.io/github/stars/madkoding/docker-slimevr-web-server) ![Forks](https://img.shields.io/github/forks/madkoding/docker-slimevr-web-server) [![Publish Status](https://github.com/madkoding/docker-slimevr-web-server/actions/workflows/docker-publish.yml/badge.svg)](https://github.com/madkoding/docker-slimevr-web-server/actions/workflows/docker-publish.yml) ![Docker Pulls](https://img.shields.io/docker/pulls/madkoding/slimevr-web-server)
4-
5-
This project contains a complete Docker environment to run the [SlimeVR Server](https://github.com/SlimeVR/SlimeVR-Server) with a dynamic Web GUI, ideal for headless setups like Raspberry Pi, home servers, or LAN PCs.
1+
# SlimeVR Server + Web GUI (Docker)
2+
3+
![Stars](https://img.shields.io/github/stars/madkoding/docker-slimevr-web-server)
4+
![Forks](https://img.shields.io/github/forks/madkoding/docker-slimevr-web-server)
5+
[![Publish Status](https://github.com/madkoding/docker-slimevr-web-server/actions/workflows/docker-publish.yml/badge.svg)](https://github.com/madkoding/docker-slimevr-web-server/actions/workflows/docker-publish.yml)
6+
![Docker Pulls](https://img.shields.io/docker/pulls/madkoding/slimevr-web-server)
7+
8+
Run [SlimeVR Server](https://github.com/SlimeVR/SlimeVR-Server) and its Web GUI in Docker with a setup that works across Linux, macOS, and Windows, plus an optimized Linux hotplug mode for direct USB tracker usage.
9+
10+
## Features
11+
12+
- Auto-downloads `slimevr.jar` and `slimevr-gui-dist.tar.gz` from official releases
13+
- Single `.env` configuration for version and Web GUI port
14+
- Nginx-served Web GUI with automatic `?ip=` redirect
15+
- Cross-platform default compose profile (Docker Desktop friendly)
16+
- Linux override profile for stable USB/HID hotplug behavior
17+
18+
## Project Structure
19+
20+
```text
21+
.
22+
|- .env
23+
|- docker-compose.yml
24+
|- docker-compose.linux.yml
25+
|- nginx/
26+
| |- Dockerfile
27+
| |- entrypoint.sh
28+
| \- templates/
29+
| \- default.conf.template
30+
\- slimevr/
31+
\- Dockerfile
32+
```
633

7-
## 🚀 Features
34+
## Requirements
835

9-
- Automatic download of `.jar` and Web GUI assets from GitHub
10-
- Fully configurable via `.env` file
11-
- Web GUI served through Nginx
12-
- Auto-redirects with `?ip=<your-host-ip>`
13-
- All relevant ports exposed (SlimeVR, VMC, OSC, etc.)
14-
- Simple and production-ready setup 💯
36+
- Docker Engine 24+ (or Docker Desktop)
37+
- Docker Compose v2 (`docker compose`)
1538

16-
---
39+
## Configuration
1740

18-
## 📁 Project structure
41+
Edit `.env`:
1942

43+
```env
44+
SLIMEVR_VERSION=19.0.0-rc.1
45+
WEBGUI_PORT=8080
2046
```
21-
slimevr-docker/
22-
├── .env
23-
├── docker-compose.yml
24-
├── nginx/
25-
│ ├── Dockerfile
26-
│ ├── entrypoint.sh
27-
│ └── templates/
28-
│ └── default.conf.template
29-
├── slimevr/
30-
│ └── Dockerfile
31-
```
32-
33-
---
3447

35-
## ⚙️ Configuration
48+
## Run
3649

37-
Edit the `.env` file:
50+
### Option A: Cross-platform default (Linux/macOS/Windows)
3851

39-
```env
40-
SLIMEVR_VERSION=0.14.1 # SlimeVR Server version to download
41-
WEBGUI_PORT=8080 # Port to serve the Web GUI
52+
```bash
53+
docker compose up -d
4254
```
4355

44-
---
56+
This mode uses explicit port mappings and is the recommended default for Docker Desktop users.
4557

46-
## 🧱 Build & Run
58+
### Option B: Linux USB hotplug mode (recommended for direct USB trackers)
4759

4860
```bash
49-
docker compose --env-file .env build
50-
docker compose --env-file .env up -d
61+
docker compose -f docker-compose.yml -f docker-compose.linux.yml up -d
5162
```
5263

53-
Then open in your browser:
64+
This mode enables host networking and mounts `/dev` + `/run/udev` for resilient USB/HID reattach behavior.
5465

55-
```
56-
http://<SLIMEVR_IP>:<WEBGUI_PORT>/
57-
```
66+
## Access the Web GUI
5867

59-
→ It will redirect automatically to:
68+
Open:
6069

61-
```
62-
http://<SLIMEVR_IP>:<WEBGUI_PORT>/?ip=<SLIMEVR_IP>
70+
```text
71+
http://<HOST_IP>:<WEBGUI_PORT>/
6372
```
6473

65-
---
74+
The GUI auto-redirects to:
6675

67-
## 🌐 Web GUI
76+
```text
77+
http://<HOST_IP>:<WEBGUI_PORT>/?ip=<HOST_IP>
78+
```
6879

69-
The GUI is served through Nginx and is downloaded automatically from:
80+
## Ports
7081

71-
- [slimevr.jar](https://github.com/SlimeVR/SlimeVR-Server/releases)
72-
- [slimevr-gui-dist.tar.gz](https://github.com/SlimeVR/SlimeVR-Server/releases)
82+
| Service | Port(s) | Protocol |
83+
|---|---|---|
84+
| SlimeVR Trackers | 6969 | UDP |
85+
| Web GUI | `WEBGUI_PORT` | TCP |
86+
| WebSocket Bridge | 21110 | TCP |
87+
| OSC Router | 9000, 9002 | TCP/UDP |
88+
| VRC OSC | 9000, 9001 | TCP/UDP |
89+
| VMC | 39539, 39540 | TCP/UDP |
90+
| Legacy Discovery | 4768 | UDP |
7391

74-
---
92+
## Volumes
7593

76-
## 🧩 Exposed Ports
94+
- `slimevr-config`: persistent SlimeVR config (`vrconfig.yml`)
95+
- `slimevr-gui`: GUI static assets shared between app and Nginx
7796

78-
| Service | Port(s) | Protocol |
79-
|------------------|---------------|----------|
80-
| SlimeVR Trackers | 6969 | UDP |
81-
| Web GUI | `WEBGUI_PORT` | TCP |
82-
| WebSocket Bridge | 21110 | TCP |
83-
| OSC Router | 9000, 9002 | TCP/UDP |
84-
| VRC OSC | 9000, 9001 | TCP/UDP |
85-
| VMC | 39539, 39540 | TCP/UDP |
97+
## Troubleshooting
8698

87-
---
99+
- `ERR_TOO_MANY_REDIRECTS`: ensure redirect is only applied when `?ip=` is missing.
100+
- Nginx error `server directive is not allowed here`: do not replace `nginx.conf` with a `server {}` block; use `conf.d/default.conf`.
101+
- Linux USB not detected: run with `docker-compose.linux.yml` (hotplug mode).
102+
- macOS/Windows USB passthrough: Docker Desktop does not expose raw USB devices to Linux containers like native Linux does. For direct USB trackers, use Linux (native/VM/WSL2 with USB/IP).
103+
- Port already in use (`6969` or `21110`): stop conflicting processes or containers.
88104

89-
## 🗂 Volumes
105+
Check conflicts:
90106

91-
- `slimevr-config`: Persistent SlimeVR config (`vrconfig.yml`)
92-
- `slimevr-gui`: Static files for the GUI served by Nginx
107+
```bash
108+
sudo ss -ltnup | grep -E '(:6969|:21110)'
109+
```
93110

94-
---
111+
## Update
95112

96-
## 🧪 Troubleshooting
113+
To update SlimeVR, set a new `SLIMEVR_VERSION` in `.env` and recreate:
114+
115+
```bash
116+
docker compose up -d --build
117+
```
97118

98-
- **ERR_TOO_MANY_REDIRECTS**: Make sure the Nginx redirect only happens if `?ip=` is missing in the URL.
99-
- **Nginx crash with “server directive not allowed”**: Don't overwrite `nginx.conf` with a `server {}` block. Use `conf.d/default.conf` instead.
100-
- **USB not detected**: Check you're mapping the correct port (e.g. `/dev/ttyUSB0`). Adjust it based on your hardware.
119+
For Linux hotplug mode:
101120

102-
---
121+
```bash
122+
docker compose -f docker-compose.yml -f docker-compose.linux.yml up -d --build
123+
```
103124

104-
## 🧡 Credits
125+
## Credits
105126

106127
- [SlimeVR](https://slimevr.dev/)
107-
- Web GUI based on [slimevr-gui-dist](https://github.com/SlimeVR/SlimeVR-Server/releases)
128+
- Web GUI assets from the official [SlimeVR releases](https://github.com/SlimeVR/SlimeVR-Server/releases)
108129

109-
---
110-
111-
## 📝 License
130+
## License
112131

113132
MIT
114133

115-
---
116-
117134
## Donations
118135

119-
BTC: bc1qrd3mexqu43qn0597d248725kdp3tr28252q64p
136+
BTC: `bc1qrd3mexqu43qn0597d248725kdp3tr28252q64p`
120137

121138
<!-- AUTO-UPDATE-DATE -->
122-
**Última actualización:** 2026-02-26 15:50:57 -03
139+
**Last updated:** 2026-04-02

0 commit comments

Comments
 (0)