openvibers/source.openvibe.games LINUX_SETUP.md

LINUX_SETUP.md

main 11.9 KB · 544 lines · markdown

Raw HistoryBlame Repository
1# OpenVibe: Source - Linux Setup & Run Guide
2
3Complete step-by-step guide to set up and run OpenVibe: Source on Linux.
4
5## Prerequisites
6
7### System Requirements
8- Ubuntu 20.04 LTS or later (tested on 22.04 LTS)
9- 50GB free disk space (SRCDS + Steam apps)
10- 8GB RAM minimum (16GB recommended for multiple servers)
11- 4-core CPU minimum
12
13### Required Software
14
15#### 1. Install system dependencies
16```bash
17sudo apt-get update
18sudo apt-get install -y \
19 git curl wget build-essential \
20 python3 python3-pip \
21 node.js npm \
22 wine wine32 wine64 winetricks \
23 lib32gcc-s1 lib32stdc++6 \
24 libssl-dev libffi-dev \
25 postgresql postgresql-contrib \
26 docker.io docker-compose \
27 tmux screen \
28 jq
29```
30
31#### 2. Install Proton Experimental (for SRCDS on Linux)
32```bash
33# Download Proton Experimental if using newer Steam
34# For Proton 8.x+, set up environment:
35export PROTON_VERSION="experimental"
36export STEAM_COMPAT_TOOLS_PATHS="/home/$USER/.steam/root/compatibilitytools.d"
37
38# Or use native SRCDS if available for your engine version
39```
40
41#### 3. Install Steam and SteamCMD
42```bash
43mkdir -p ~/steamcmd
44cd ~/steamcmd
45curl -sqL "https://steamcdn-a.akamaihd.net/client/installer/steamcmd_linux.tar.gz" | tar zxvf -
46
47# Login to Steam
48./steamcmd.sh
49 > login anonymous
50 > quit
51
52# Add to PATH
53echo 'export PATH="$PATH:$HOME/steamcmd"' >> ~/.bashrc
54source ~/.bashrc
55```
56
57#### 4. Install Team Fortress 2 (for BSP compilation tools)
58```bash
59steamcmd.sh \
60 +login anonymous \
61 +app_update 440 validate \
62 +quit
63
64# Wait for download (~15GB)
65```
66
67#### 5. Install HL2: Deathmatch (game base)
68```bash
69steamcmd.sh \
70 +login anonymous \
71 +app_update 320 validate \
72 +quit
73```
74
75## OpenVibe Setup
76
77### 1. Clone the repository
78```bash
79cd ~
80git clone https://github.com/yourusername/openvibe-source.git
81cd openvibe-source
82```
83
84### 2. Set up environment variables
85```bash
86# Create ~/.bashrc additions
87cat >> ~/.bashrc << 'EOF'
88export OPENVIBE_ROOT="$HOME/openvibe-source"
89export TF2_INSTALL_DIR="$HOME/.steam/steam/SteamApps/common/Team Fortress 2"
90export HL2_INSTALL_DIR="$HOME/.steam/steam/SteamApps/common/Half-Life 2 Deathmatch"
91export SRCDS_DIR="$HOME/srcds"
92export OV_API_ENDPOINT="http://localhost:3000"
93export OV_API_SECRET="your-secret-key-here"
94EOF
95
96source ~/.bashrc
97```
98
99### 3. Set up SRCDS installation
100```bash
101# Create SRCDS directory structure
102mkdir -p $SRCDS_DIR/hlserver/orangebox/cfg
103mkdir -p $SRCDS_DIR/hlserver/orangebox/maps
104mkdir -p $SRCDS_DIR/hlserver/orangebox/logs
105
106# Copy game files from HL2:DM installation
107cp -r "$HL2_INSTALL_DIR/hl2mp" "$SRCDS_DIR/hlserver/orangebox/"
108cp -r "$HL2_INSTALL_DIR/bin" "$SRCDS_DIR/hlserver/orangebox/"
109cp -r "$HL2_INSTALL_DIR/orange.gcf" "$SRCDS_DIR/hlserver/orangebox/" || true
110```
111
112### 4. Set up PostgreSQL database
113```bash
114# Start PostgreSQL
115sudo systemctl start postgresql
116
117# Create database
118sudo -u postgres psql << 'EOF'
119CREATE DATABASE openvibe;
120CREATE USER openvibe WITH PASSWORD 'openvibe_dev_password';
121ALTER ROLE openvibe SET client_encoding TO 'utf8';
122ALTER ROLE openvibe SET default_transaction_isolation TO 'read committed';
123ALTER ROLE openvibe SET default_transaction_deferrable TO on;
124ALTER ROLE openvibe SET timezone TO 'UTC';
125GRANT ALL PRIVILEGES ON DATABASE openvibe TO openvibe;
126EOF
127
128# Initialize database schema
129cd $OPENVIBE_ROOT/backend
130npm install
131npm run db:migrate
132```
133
134### 5. Install backend dependencies
135```bash
136cd $OPENVIBE_ROOT/backend
137npm install
138npm run build
139```
140
141### 6. Compile maps (requires Wine + TF2 tools)
142```bash
143cd $OPENVIBE_ROOT
144
145# Make script executable
146chmod +x tools/compile-dev-maps-wine.sh
147
148# Compile all maps (VIS can be slow, skip with VVIS_ENABLED=0)
149VVIS_ENABLED=0 ./tools/compile-dev-maps-wine.sh
150
151# Copy compiled BSPs to SRCDS
152cp game/openvibe.games/maps/*.bsp $SRCDS_DIR/hlserver/orangebox/hl2mp/maps/
153```
154
155### 7. Copy OpenVibe game content
156```bash
157# Copy scripts
158mkdir -p $SRCDS_DIR/hlserver/orangebox/hl2mp/scripts/vscripts
159cp game/openvibe.games/scripts/vscripts/*.nut \
160 $SRCDS_DIR/hlserver/orangebox/hl2mp/scripts/vscripts/
161
162# Copy configs
163mkdir -p $SRCDS_DIR/hlserver/orangebox/hl2mp/cfg
164cp game/openvibe.games/cfg/*.cfg \
165 $SRCDS_DIR/hlserver/orangebox/hl2mp/cfg/
166
167# Copy resources
168mkdir -p $SRCDS_DIR/hlserver/orangebox/hl2mp/resource
169cp game/openvibe.games/resource/*.txt \
170 $SRCDS_DIR/hlserver/orangebox/hl2mp/resource/
171
172# Copy particles
173mkdir -p $SRCDS_DIR/hlserver/orangebox/hl2mp/particles
174cp game/openvibe.games/particles/* \
175 $SRCDS_DIR/hlserver/orangebox/hl2mp/particles/
176```
177
178## Configuration
179
180### 1. Configure server.cfg
181```bash
182cat > $SRCDS_DIR/hlserver/orangebox/hl2mp/cfg/server.cfg << 'EOF'
183// OpenVibe Server Configuration
184
185// Server settings
186hostname "OpenVibe - Hub [US-East]"
187rcon_password "your-secure-rcon-password"
188
189// OpenVibe settings
190ov_api_endpoint "http://localhost:3000"
191ov_server_id "us-east-hub-01"
192ov_server_secret "your-server-secret"
193
194// Network
195rate 30000
196cl_cmdrate 66
197sv_mincmdrate 10
198
199// Gameplay
200mp_friendlyfire 0
201mp_falldamage 0
202mp_teamplay 1
203
204// Logging
205log on
206sv_log_onefile 1
207EOF
208```
209
210### 2. Configure backend API (.env)
211```bash
212cat > $OPENVIBE_ROOT/backend/.env << 'EOF'
213# Database
214DATABASE_URL="postgresql://openvibe:openvibe_dev_password@localhost:5432/openvibe"
215
216# Server
217NODE_ENV="production"
218PORT=3000
219LOG_LEVEL="info"
220
221# Admin
222ADMIN_SECRET_KEY="your-admin-secret-key"
223
224# Steam
225STEAM_APP_ID="YOUR_STEAM_APP_ID"
226STEAM_API_KEY="your-steam-api-key"
227EOF
228```
229
230## Running the Servers
231
232### 1. Start the API backend
233```bash
234cd $OPENVIBE_ROOT/backend
235npm start
236
237# Or with Docker
238cd $OPENVIBE_ROOT
239docker-compose -f infra/docker-compose.yml up -d
240```
241
242### 2. Start all game servers (via tmux)
243```bash
244# Make dev-up script executable
245chmod +x $OPENVIBE_ROOT/tools/dev-up.sh
246
247# Start all 5 servers + sidecar
248$OPENVIBE_ROOT/tools/dev-up.sh
249
250# Attach to tmux session to view output
251tmux attach-session -t openvibe
252```
253
254### 3. Manual server startup (single server)
255```bash
256# For Hub server
257cd $SRCDS_DIR/hlserver
258./srcds_run -game hl2mp \
259 +map ov_hub \
260 -maxplayers 32 \
261 -port 27015 \
262 +sv_pure 0 \
263 +exec server.cfg \
264 -console
265
266# For Prop Hunt server
267cd $SRCDS_DIR/hlserver
268./srcds_run -game hl2mp \
269 +map ph_openvibe_dev \
270 -maxplayers 16 \
271 -port 27016 \
272 +sv_pure 0 \
273 +exec server.cfg \
274 -console
275```
276
277### 4. Connect client
278```bash
279# With Proton Experimental
280PROTON_EXPERIMENTAL=1 steam steam://run/320//-console +connect 127.0.0.1:27015
281
282# Or via console
283> connect 127.0.0.1:27015
284> ov_join hub
285```
286
287## Troubleshooting
288
289### Game server won't start
290```bash
291# Check SRCDS binary exists
292ls -la $SRCDS_DIR/hlserver/srcds_run
293
294# Run with verbose output
295./srcds_run -game hl2mp +map ov_hub -console -debug
296
297# Check for missing libraries
298ldd ./srcds_i486
299```
300
301### API connection fails
302```bash
303# Check backend is running
304curl http://localhost:3000/health
305
306# Check logs
307docker logs openvibe_api
308
309# Verify PostgreSQL
310sudo -u postgres psql openvibe -c "SELECT 1;"
311```
312
313### BSP compilation errors
314```bash
315# Check TF2 installation
316ls -la "$TF2_INSTALL_DIR/bin/"
317
318# Run VBSP manually for debugging
319WINEARCH=win32 wine "$TF2_INSTALL_DIR/bin/vbsp.exe" \
320 -game "$TF2_INSTALL_DIR/tf" \
321 "$OPENVIBE_ROOT/game/openvibe.games/maps/ov_hub.vmf"
322```
323
324### VScript errors in server console
325```bash
326# Check script files exist
327ls -la $SRCDS_DIR/hlserver/orangebox/hl2mp/scripts/vscripts/
328
329# Enable VScript logging
330sv_script_debug 1
331
332# Check logs directory has write permissions
333chmod 777 $SRCDS_DIR/hlserver/orangebox/hl2mp/logs
334```
335
336### Player can't join servers
337```bash
338# Check firewall rules
339sudo ufw status
340sudo ufw allow 27015:27020/udp
341sudo ufw allow 27015:27020/tcp
342
343# Check SRCDS is listening
344netstat -tulnp | grep -E "27015|27016|27017|27018|27019"
345
346# Verify server loads map correctly
347# Look for: "Didn't load map" errors in console
348```
349
350## Development Workflow
351
352### 1. Modify VScript logic
353```bash
354# Edit game mode script
355nano $OPENVIBE_ROOT/game/openvibe.games/scripts/vscripts/ov_prophunt.nut
356
357# Changes take effect on map reload (no restart needed)
358# In-game console: `changelevel ph_openvibe_dev`
359```
360
361### 2. Modify backend API
362```bash
363# Edit endpoint
364nano $OPENVIBE_ROOT/backend/src/app.ts
365
366# Rebuild TypeScript
367cd $OPENVIBE_ROOT/backend
368npm run build
369
370# Restart API
371docker-compose -f infra/docker-compose.yml restart api
372```
373
374### 3. Update maps
375```bash
376# Edit VMF in Hammer Editor (if available)
377# Or modify generator
378nano $OPENVIBE_ROOT/tools/generate-dev-vmfs.mjs
379
380# Regenerate and compile
381cd $OPENVIBE_ROOT
382./tools/compile-dev-maps-wine.sh
383
384# Copy new BSP
385cp game/openvibe.games/maps/ph_openvibe_dev.bsp $SRCDS_DIR/hlserver/orangebox/hl2mp/maps/
386
387# Reload map in-game
388```
389
390## Monitoring
391
392### Check server status
393```bash
394# List running SRCDS processes
395ps aux | grep srcds
396
397# Check port availability
398netstat -tulnp | grep -E "27015|27016|27017"
399
400# Check API health
401curl http://localhost:3000/health | jq .
402```
403
404### View logs
405```bash
406# SRCDS logs
407tail -f $SRCDS_DIR/hlserver/orangebox/hl2mp/logs/L*.log
408
409# API logs
410docker logs -f openvibe_api
411
412# Sidecar logs
413tmux capture-pane -t openvibe:sidecar -p
414
415# PostgreSQL logs
416sudo tail -f /var/log/postgresql/postgresql.log
417```
418
419## Performance Tuning
420
421### Increase SRCDS performance
422```bash
423# Adjust rate limits for better responsiveness
424rate 30000
425cl_cmdrate 66
426sv_mincmdrate 10
427
428# Adjust tickrate (higher = more CPU usage)
429sv_tickrate 66
430```
431
432### Database optimization
433```bash
434# Enable query logging
435sudo -u postgres psql openvibe -c "ALTER SYSTEM SET log_min_duration_statement = 100;"
436sudo systemctl restart postgresql
437
438# Check indexes
439sudo -u postgres psql openvibe -c "\d+ players"
440sudo -u postgres psql openvibe -c "\d+ matches"
441```
442
443## Deployment to Production
444
445### 1. Use environment-specific configs
446```bash
447# Production backend config
448cp $OPENVIBE_ROOT/backend/.env.example $OPENVIBE_ROOT/backend/.env.production
449# Edit with real credentials and settings
450nano $OPENVIBE_ROOT/backend/.env.production
451```
452
453### 2. Use Docker for all services
454```bash
455# Production docker-compose
456docker-compose -f infra/docker-compose.yml up -d
457
458# Enable restart policy
459docker update --restart=unless-stopped openvibe_api
460docker update --restart=unless-stopped openvibe_db
461```
462
463### 3. Set up SSL/TLS reverse proxy
464```bash
465# Use nginx or similar
466# Configure with valid certificates
467# Point to http://localhost:3000 backend
468```
469
470### 4. Enable server monitoring
471```bash
472# Use systemd service files for SRCDS instances
473# Set up Prometheus/Grafana for metrics
474# Configure alerts for server crashes
475```
476
477## Useful Commands
478
479```bash
480# List all tmux sessions
481tmux list-sessions
482
483# Attach to specific server
484tmux attach-session -t openvibe:hub
485
486# Kill all servers
487tmux kill-session -t openvibe
488
489# Check SRCDS console remotely
490tmux capture-pane -t openvibe:hub -p
491
492# Execute command on server
493tmux send-keys -t openvibe:hub "say Hello from console" Enter
494
495# View leaderboard
496curl "http://localhost:3000/v1/leaderboard?limit=10" | jq .
497
498# Create admin shop item
499curl -X POST http://localhost:3000/v1/admin/shop/items \
500 -H "Content-Type: application/json" \
501 -H "X-Admin-Secret: your-admin-secret" \
502 -d '{"name":"Cool Skin","type":"model","price":5000}'
503```
504
505## Support & Debugging
506
507### Enable verbose logging
508```bash
509# In server.cfg
510developer 2
511sv_log_onefile 1
512sv_script_debug 1
513
514# In OpenVibe config
515OV_DEBUG=1
516```
517
518### Generate debug package
519```bash
520cd $OPENVIBE_ROOT
521mkdir -p debug-export
522cp game/openvibe.games/scripts/vscripts/*.nut debug-export/
523cp tools/ov-sidecar.mjs debug-export/
524docker logs openvibe_api > debug-export/api.log
525docker logs openvibe_db > debug-export/db.log
526# Tar for sharing
527tar czf openvibe-debug-$(date +%Y%m%d-%H%M%S).tar.gz debug-export/
528```
529
530## Next Steps
531
5321. **Customize game modes** - Edit VScript files to adjust gameplay
5332. **Add more cosmetics** - Use `/v1/admin/shop/items` to add items
5343. **Set up web dashboard** - Create a web UI that connects to the API
5354. **Configure Steam integration** - Add proper Steam authentication
5365. **Deploy to production** - Use Docker Swarm or Kubernetes
537
538---
539
540For more information, see:
541- [Architecture Documentation](./docs/architecture.md)
542- [Backend API Docs](./backend/README.md)
543- [VScript Reference](./game/openvibe.games/scripts/vscripts/ov_shared.nut)
544