English

VoceSpace Flexible Deployment Guide

This document describes how to deploy the vocespace-client front-end project on an Ubuntu server, configure Nginx + HTTPS, install dependencies, use PM2 to manage services, and configure TURN services for WebRTC.

Get and build the project (optional)

You don't actually need to clone the project manually, we have already helped you do it in the automated deployment script.

1# Clone the project
2git clone https://github.com/your-org/vocespace-client.git vocespace-client

Install and configure Nginx

Install Nginx and Certbot

Make sure the system is updated and install the required packages:

1apt update
2apt install nginx certbot python3-certbot-nginx -y

WARNING

If you are using CentOS or other non-Debian distributions, please replace with the corresponding package management command (such as yum or dnf).
certbot and python3-certbot-nginx are tools for automatically configuring HTTPS.

Configure `nginx.conf` (global configuration)

Path: /etc/nginx/nginx.conf

1user  nginx;
2worker_processes  auto;
3
4error_log  /var/log/nginx/error.log warn;
5pid        /var/run/nginx.pid;
6
7events {
8    worker_connections  1024;
9}
10
11http {
12    include       /etc/nginx/mime.types;
13    default_type  application/octet-stream;
14
15    log_format  main  '$remote_addr - $remote_user [$time_local] "$request" '
16                      '$status $body_bytes_sent "$http_referer" '
17                      '"$http_user_agent" "$http_x_forwarded_for"';
18
19    access_log  /var/log/nginx/access.log  main;
20
21    sendfile        on;
22    keepalive_timeout  65;
23
24    include /etc/nginx/conf.d/*.conf;
25}

NOTE

This is a global configuration and usually does not need to be changed frequently.
It is recommended to enable logrotate for the log directory to avoid disk fullness.

Configure site files (virtual host configuration)

Path recommendation: /etc/nginx/sites-enabled/livemeet.conf or /etc/nginx/conf.d/livemeet.conf

1# HTTP to HTTPS redirection
2server {
3    listen 80;
4    listen [::]:80;
5
6    server_name your.server.name;
7
8    location /.well-known/acme-challenge/ {
9        root /var/www/certbot;
10    }
11
12    location / {
13        return 301 https://$host$request_uri;
14    }
15}
16
17# HTTPS reverse proxy configuration
18server {
19    listen 443 ssl;
20    listen [::]:443 ssl;
21
22    server_name your.server.name;
23
24    ssl_certificate /etc/letsencrypt/live/your.server.name/fullchain.pem;
25    ssl_certificate_key /etc/letsencrypt/live/your.server.name/privkey.pem;
26    include /etc/letsencrypt/options-ssl-nginx.conf;
27    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;
28
29    # Application main service (such as front-end or back-end web interface)
30    location / {
31        proxy_pass http://127.0.0.1:3000;
32        proxy_http_version 1.1;
33        proxy_set_header Upgrade $http_upgrade;
34        proxy_set_header Connection "Upgrade";
35        proxy_set_header Host $host;
36        proxy_cache_bypass $http_upgrade;
37    }
38
39    # WebRTC service proxy (port and path depend on the project)
40    location /rtc {
41        proxy_pass http://127.0.0.1:7880;
42        proxy_http_version 1.1;
43        proxy_set_header Upgrade $http_upgrade;
44        proxy_set_header Connection "Upgrade";
45        proxy_set_header Host $host;
46    }
47
48    # Socket.IO real-time communication proxy
49    # location /socket.io {
50    #    proxy_pass http://127.0.0.1:3000;  # Please modify according to the actual port
51    #    proxy_http_version 1.1;
52    #    proxy_set_header Upgrade $http_upgrade;
53    #    proxy_set_header Connection "Upgrade";
54    #    proxy_set_header Host $host;
55    #    proxy_set_header X-Real-IP $remote_addr;
56    #    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
57    #    proxy_set_header X-Forwarded-Proto $scheme;
58    #    proxy_cache_bypass $http_upgrade;
59    # }
60}

WARNING

server_name must be consistent with the domain name of the certificate you actually applied for.
Please make sure that the files in /etc/letsencrypt/live/your.server.name/ have been generated The ssl configuration is generated by certbot

2.4 Start and check the status of Nginx

1# Check if the configuration is correct
2nginx -t
3
4# Reload the configuration (recommended) or restart the service
5systemctl reload nginx
6# or
7systemctl restart nginx

Apply for HTTPS certificate using Certbot

Make sure the domain name is correctly resolved to the server IP in the DNS service provider.

Certificate issuance command

1certbot --nginx -d your.server.name --register-unsafely-without-email

NOTE

--nginx: Certbot will automatically modify your nginx configuration to enable HTTPS.
--register-unsafely-without-email: Do not bind an email address. Not recommended for official use, it is recommended to add --email your@email.com.

Verify Nginx status and restart

1nginx -t
2systemctl reload nginx

HTTPS and automatic certificate renewal (Certbot)

1sudo apt update
2sudo apt install certbot python3-certbot-nginx -y
3
4# Obtain and configure certificates
5sudo certbot --nginx -d example.com
6
7# Test automatic renewal
8sudo certbot renew --dry-run

Front-end dependency installation and pm2 management

We can manage the VoceSpace project by using pm2

1# Install PM2
2pnpm add -g pm2
3
4# Start automatically at boot
5pm2 startup
6pm2 save

Check pm2 status

1pm2 status

Coturn TURN server deployment

Used for WebRTC communication penetration.

Install Coturn

1sudo apt install coturn -y

To start automatically when opening the server, you must modify the /etc/default/coturn file.

1sudo vim /etc/default/coturn

Find the following line and uncomment it to run Coturn as an automatic system service daemon.

1TURNSERVER_ENABLED=1

Edit the configuration file

Edit /etc/turnserver.conf:

1server-name=your.server.name
2listening-ip=0.0.0.0
3listening-port=3478
4fingerprint
5lt-cred-mech
6user=username:password
7realm=your.server.name
8external-ip=158.247.198.2
9min-port=49152
10max-port=65535

start Coturn

1sudo systemctl enable coturn
2sudo systemctl start coturn
3sudo systemctl restart coturn

Test TURN service

You can use the WebRTC test page such as:

https://webrtc.github.io/samples/src/content/peerconnection/trickle-ice/

Use the following configuration:

1{
2  "urls": "turn:example.com:3478",
3  "username": "user",
4  "credential": "password"
5}

Automated deployment script

We provide a complete automated deployment script. After you have installed and configured Nginx, Certbot, pm2, Node (pnpm), Coturn (optional) on the server, you can directly copy our automated deployment script for one-click deployment!

1#!/bin/bash
2
3#=========================================================================#
4# shell script for deploy prod environment
5#=========================================================================#
6
7#=========================================================================#
8# Variables --------------------------------------------------------------#
9#=========================================================================#
10ROOT_PATH="/root/vocespace-client/"
11KIND="prod"
12PKG_NAME="vocespace_prod"
13REPO_URL="https://github.com/Privoce/vocespace-client.git"
14BRANCH="main"
15DEPLOY_NGINX_CONF="vocespace"
16NGINX_CONF="nginx.conf"
17NGINX_AVA_PATH="/etc/nginx/sites-available"
18NGINX_ENABLED_PATH="/etc/nginx/sites-enabled"
19LOG_FILE="deploy_prod.log"
20LOG_SRC="/root/deploy_log"
21LOG_PATH="$LOG_SRC/$LOG_FILE"
22ERROR_FMT="AUTO DEPLOY ERROR: See $LOG_PATH for more details"
23#=========================================================================#
24# clear or create log file -----------------------------------------------#
25#=========================================================================#
26# check or create log src
27if [ ! -d $LOG_SRC ]; then
28    mkdir -p $LOG_SRC
29fi
30# check or create log file
31if [ -f $LOG_PATH ]; then
32    rm $LOG_PATH
33fi
34touch $LOG_PATH
35#=========================================================================#
36# Clone or pull and then do pkg (prod)-------------------------------------#
37#=========================================================================#
38# check if the root path is exist
39if [ ! -d $ROOT_PATH ]; then
40    mkdir -p $ROOT_PATH
41fi
42
43cd $ROOT_PATH
44
45# do clone if vocespace_prod not exist or cd and do pull
46if [ ! -d $ROOT_PATH/$PKG_NAME ]; then
47    git clone --branch $BRANCH $REPO_URL $PKG_NAME
48    if [ $? -ne 0 ]; then
49        echo "clone vocespace_prod from github repo failed!" >> $LOG_PATH
50        echo $ERROR_FMT
51        exit 1
52    fi
53    echo "SYSTEM: clone vocespace_prod from github repo success" >> $LOG_PATH
54    # set remote url for future pull
55    cd $ROOT_PATH/$PKG_NAME
56    git remote set-url origin $REPO_URL
57else
58    cd $ROOT_PATH/$PKG_NAME
59    # set remote url
60    git remote set-url origin $REPO_URL
61    # do fetch and reset
62    git fetch --all
63    if [ $? -ne 0 ]; then
64        echo "fetch from github repo failed!" >> $LOG_PATH
65        echo $ERROR_FMT
66        exit 1
67    fi
68    git reset --hard origin/$BRANCH
69    if [ $? -ne 0 ]; then
70        echo "reset to origin/$BRANCH failed!" >> $LOG_PATH
71        echo $ERROR_FMT
72        exit 1
73    fi
74    echo "SYSTEM: pull vocespace_prod from github repo success" >> $LOG_PATH
75fi
76#=========================================================================#
77# Build environment ------------------------------------------------------#
78#=========================================================================#
79# make a .env file
80# the following is standard .env file content:
81# ```
82# LIVEKIT_API_KEY=devkey
83# LIVEKIT_API_SECRET=secret
84# LIVEKIT_URL=wss://space.voce.chat
85# NODE_ENV=production
86# ```
87# - remove the old .env file and replace with new one
88if [ -f .env ]; then
89    rm .env
90fi
91echo "LIVEKIT_API_KEY=devkey" >> .env
92echo "LIVEKIT_API_SECRET=secret" >> .env
93echo "LIVEKIT_URL=ws://localhost:7880" >> .env
94echo "WEBHOOK=false" >> .env
95#=========================================================================#
96# install dependencies and build -----------------------------------------#
97#=========================================================================#
98# do pnpm install and build
99pnpm install
100if [ $? -ne 0 ]; then
101    echo "pnpm install failed!" >> $LOG_PATH
102    echo $ERROR_FMT
103    exit 1
104fi
105# - set NODE_OPTIONS for build add heap size to 8192
106export NODE_OPTIONS="--max-old-space-size=8192"
107# - build the project
108pnpm build
109if [ $? -ne 0 ]; then
110    echo "pnpm build failed!" >> $LOG_PATH
111    echo $ERROR_FMT
112    exit 1
113fi
114echo "SYSTEM: pnpm install and build success" >> $LOG_PATH
115#=========================================================================#
116# pm2 stop and delete old version then pub--------------------------------#
117#=========================================================================#
118# stop $PKG_NAME
119pm2 stop $PKG_NAME
120# delete $PKG_NAME
121pm2 delete $PKG_NAME
122# start pm2 npm 
123PORT=3000 pm2 start npm --name $PKG_NAME -- start
124# save pm2
125pm2 save
126# sleep 2s for pm2 server to start
127sleep 2
128# netstat -tulnp | grep 3030 to check if the server is running, if have echo success
129if [ $(netstat -tulnp | grep 3000 | wc -l) -gt 0 ]; then
130    echo "pm2 server rebuild success!" >> $LOG_PATH
131else 
132    echo "pm2 server rebuild failed!" >> $LOG_PATH
133    echo $ERROR_FMT
134    exit 1
135fi
136# echo all done
137echo "Deploy Prod: All done! Please check $LOG_PATH for more details to make sure everything is fine."
138exit 0

Table of Contents

VoceSpace Flexible Deployment Guide#

Get and build the project (optional)#

Install and configure Nginx#

Install Nginx and Certbot#

Configure nginx.conf (global configuration)#

Configure site files (virtual host configuration)#

2.4 Start and check the status of Nginx#

Apply for HTTPS certificate using Certbot#

Certificate issuance command#

Verify Nginx status and restart#

HTTPS and automatic certificate renewal (Certbot)#

Front-end dependency installation and pm2 management#

Check pm2 status#

Coturn TURN server deployment#

Install Coturn#

Edit the configuration file#

start Coturn#

Test TURN service#

Automated deployment script#