VoceSpace QuickStart#

This document describes how to use the provided automation script to deploy VoceSpace.

Support for one-click deployment of VoceSpace + LiveKit Server + Redis.

File Description#

• vocespace_deploy.sh - Linux/macOS automated deployment script
• vocespace_deploy.bat - Windows automated deployment script
• README.md - Documentation

Features#

• ✅ Automatic detection of system architecture and host IP
• ✅ Support for custom configuration files
• ✅ One-click installation and startup of all necessary components
• ✅ Intelligent handling of existing services
• ✅ Detailed status checking and log output
• ✅ Support for force reinstallation and component skipping

Usage#

Linux/macOS#

1# Basic usage - use default configuration
2./vocespace_deploy.sh
3
4# Use custom configuration file
5./vocespace_deploy.sh --config ./my-config.json
6
7# Specify host IP
8./vocespace_deploy.sh --host-ip 192.168.1.100
9
10# Force reinstall all components
11./vocespace_deploy.sh --force
12
13# Skip certain component installations
14./vocespace_deploy.sh --skip-redis --skip-livekit
15
16# Combined usage
17./vocespace_deploy.sh --config ./config.json --host-ip 192.168.1.100 --force

Windows#

1REM Basic usage - use default configuration
2vocespace_deploy.bat
3
4REM Use custom configuration file
5vocespace_deploy.bat --config ./my-config.json
6
7REM Specify host IP
8vocespace_deploy.bat --host-ip 192.168.1.100
9
10REM Force reinstall all components
11vocespace_deploy.bat --force
12
13REM Skip certain component installations
14vocespace_deploy.bat --skip-redis --skip-livekit

Command Line Parameters#

Configuration File Format#

The script supports JSON format configuration files. Default configuration file example:

1{
2  "livekit": {
3    "key": "devkey",
4    "secret": "secret",
5    "url": "ws://YOUR_IP:7880"
6  },
7  "codec": "vp9",
8  "resolution": "1080p",
9  "maxBitrate": 3000000,
10  "maxFramerate": 30,
11  "priority": "medium",
12  "redis": {
13    "enabled": true,
14    "host": "YOUR_IP",
15    "port": 6379,
16    "password": "vocespace",
17    "db": 0
18  },
19  "server_url": "localhost"
20}

Note: The script will automatically replace YOUR_IP in the configuration file with the actual host IP address.

Deployment Process#

The script executes deployment in the following order:

1. Environment Check

   • Detect operating system and architecture
   • Check Docker installation and running status
   • Auto-detect or validate host IP

2. Configuration Processing

   • Verify configuration file existence and format
   • Auto-create default configuration (if not specified)
   • Update IP addresses in configuration

3. Component Installation

   • Install Redis (skippable)
   • Install LiveKit Server (skippable)

4. Images and Services

   • Pull VoceSpace Docker image for corresponding architecture
   • Start Redis service
   • Start LiveKit Server
   • Start VoceSpace container

5. Status Check

   • Verify all service running status
   • Display access addresses and management commands

Service Ports#

After deployment completion, the following ports will be used:

Troubleshooting#

Common Issues#

1. Docker not started

   ❌ Docker is not running, please start Docker service
   • Linux: sudo systemctl start docker
   • macOS/Windows: Start Docker Desktop

2. Port conflict

   Error response from daemon: port is already allocated
   • Check port usage: lsof -i :3000
   • Stop conflicting services or use --force parameter

3. Configuration file format error

   ❌ Configuration file JSON format error
   • Use JSON validation tools to check format
   • Ensure no extra commas or quotes

4. IP address detection failure

   ❌ Unable to detect host IP
   • Manually specify IP: --host-ip YOUR_IP
   • Check network connection status

Log Viewing#

• VoceSpace container logs: docker logs vocespace
• LiveKit Server logs: tail -f livekit-server.log
• Redis logs: tail -f redis.log

Service Management#

• Stop VoceSpace: docker stop vocespace

• Stop LiveKit: pkill -f livekit-server

• Stop Redis: pkill -f redis-server

• Restart VoceSpace: docker restart vocespace

• View container status: docker ps

System Requirements#

Minimum Requirements#

• CPU: 2 cores
• Memory: 4GB RAM
• Disk: 10GB available space
• Network: Stable internet connection

Supported Systems#

• Linux: Ubuntu 18.04+, CentOS 7+, Debian 10+
• macOS: 10.14+
• Windows: Windows 10/11 (requires WSL2 or Docker Desktop)

Access the application#

After deployment, you can access VoceSpace at the following address:

• VoceSpace application: http://localhost:3000 | http://127.0.0.1:3000