aheh/PrivyDrop
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
055da7888a09176e0076410cd4e8be59772cfcb5
PrivyDrop/backend/docs/DEPLOYMENT_GUIDE.en-US.md
T
david_bai 61eeae4537 后端测试ok
2025-05-21 22:47:44 +08:00

16 KiB
Raw Blame History

Privydrop Backend Deployment Guide

This guide provides comprehensive instructions for deploying the Privydrop backend application, including setting up necessary services like Redis, TURN, and Nginx (for production environments).

1. Introduction

This document will guide you through the steps of preparing your server environment, configuring dependencies, and deploying the Privydrop backend. Whether you are setting up a development/testing environment or a full production instance, this guide aims to cover the essential aspects.

2. Prerequisites

Before you begin, ensure your server environment meets the following requirements:

  • Operating System: A Linux distribution (e.g., Ubuntu 20.04 LTS or later is recommended).
  • Node.js: v18.x or later.
  • npm (or yarn): Package manager for Node.js.
  • Root or Sudo Privileges: Required for installing packages and configuring services.
  • Optional: Base Environment & Docker Image Reference: If you need to start from a very clean system environment or want to understand the base dependencies used for Docker builds, you can refer to the backend/docker/Dockerfile file (for Docker image construction) and the backend/docker/env_install.log file (which may contain dependency installation records for specific environments). For most standard Linux distributions, following the subsequent steps in this guide will suffice.

3. Dependency Services Installation and Configuration

The Privydrop backend relies on several external services.

3.1. Redis Server

Redis is used for room management, session information, and caching.

Installation (Ubuntu Example):

sudo apt update
sudo apt install redis-server

Configuration:

  • By default, Redis listens on 127.0.0.1:6379 and does not require a password. In this case, add the default Redis configuration to your environment variable file: REDIS_HOST='localhost' REDIS_PORT=6379

  • If your Redis instance is on a different host, port, or requires a password, you will need to update the environment variables accordingly (see Section 4.3).

  • Ensure Redis is running:

    sudo systemctl status redis-server
# Or for older systems
# /etc/init.d/redis-server status

  • If Redis is not running, start it:

    sudo systemctl start redis-server
# Or
# sudo /etc/init.d/redis-server start

3.2. TURN/STUN Server (Coturn)

A TURN server is crucial for WebRTC to traverse NATs and firewalls, ensuring reliable peer-to-peer connections. Coturn is a popular open-source TURN server implementation.

Installation (Ubuntu Example):

sudo apt update
sudo apt install coturn

Configuration:

  1. Enable Coturn Service: Edit /etc/default/coturn and uncomment the line:

    TURNSERVER_ENABLED=1

  2. Coturn Configuration Files: docker/TURN/turnserver_production.conf and docker/TURN/turnserver_development.conf are template configuration files for production and development environments, respectively. You do not need to modify them manually; just add the corresponding fields to your environment variable file (see step 6 in this section).

  3. Firewall Configuration: Open the necessary ports on your server's firewall (e.g., using ufw):

    • TCP & UDP 3478: For STUN and TURN.
    • TCP & UDP 5349: For TURNS (TURN over TLS/DTLS) - Primarily for production environments.
    • UDP 49152-65533: Coturn's default relay port range (configurable with min-port and max-port in turnserver.conf).
    sudo ufw allow 3478
sudo ufw allow 5349 # For TURNS in production
sudo ufw allow 49152:65535/udp
sudo ufw enable
sudo ufw status

    Note: The following configurations regarding SSL certificates and TURNS (steps 4 and 5) are primarily for production environments. If you are only setting up a development or testing environment and using unencrypted TURN (turn:your_server_public_ip:3478), you can skip these steps and only configure the development environment variables in step 6.

  4. SSL Certificate for Production (TURNS): (Production Step) If deploying for production and using TURNS (TURN over TLS), you will need an SSL certificate for your TURN domain (e.g., turn.yourdomain.com).

    • Ensure you have a DNS 'A' record pointing turn.yourdomain.com to your server's public IP.
    • Obtain a certificate using Certbot: 
      sudo apt install certbot
sudo certbot certonly --standalone -d turn.yourdomain.com
      The certificate and private key are typically stored in /etc/letsencrypt/live/turn.yourdomain.com/.

  5. SSL Certificate Permissions (Production): (Production Step) The Coturn process (usually running as user turnserver) needs permission to read the SSL certificate and key.

    • Check current permissions: 
      sudo ls -lh /etc/letsencrypt/live/turn.yourdomain.com/fullchain.pem
sudo ls -ld /etc/letsencrypt/archive/
    • If Coturn logs show permission errors: Create a group (e.g., ssl-cert), add turnserver to it, and adjust permissions: 
      sudo groupadd -f ssl-cert
# Find the user coturn runs as, usually 'turnserver' or 'coturn'
# ps aux | grep turnserver
sudo usermod -a -G ssl-cert turnserver # Replace 'turnserver' if different
sudo chown -R root:ssl-cert /etc/letsencrypt/
sudo chmod -R 750 /etc/letsencrypt/
      Verify the new permissions on /etc/letsencrypt/archive/ and /etc/letsencrypt/live/.

  6. Add Configuration to Environment Variable File: Modify your TURN server configuration information in the appropriate .env file.

    • For development/testing environments (e.g., add the following to .env.development.local): 
      # TURN Server Configuration (Development)
TURN_EXTERNAL_IP=YourServerPublicIP # e.g., 123.123.456.567
TURN_REALM=YourServerPublicIP
TURN_USERNAME=YourTurnUsername
TURN_PASSWORD=YourTurnPassword
    • For production environments (e.g., add the following to .env.production.local): 
        # TURN Server Configuration (Production)
  TURN_EXTERNAL_IP=YourServerPublicIP # e.g., 123.123.456.567
  TURN_REALM=turn.yourdomain
  TURN_USERNAME=YourTurnUsername
  TURN_PASSWORD=YourTurnPassword
  TURN_CERT_PATH=/etc/letsencrypt/live/turn.yourdomain/fullchain.pem
  TURN_KEY_PATH=/etc/letsencrypt/live/turn.yourdomain/privkey.pem

  7. Start/Restart and Test Coturn:

    # Replace "your_env_file_path" with the appropriate environment file path
# e.g.: sudo bash ./docker/TURN/configure.sh .env.development.local
# or: sudo bash ./docker/TURN/configure.sh .env.production.local
sudo bash ./docker/TURN/configure.sh your_env_file_path
sudo systemctl status coturn

    Check /var/log/turnserver.log (or your Coturn log file path) for any errors.

    Test your TURN server: Use an online tool like the Metered TURN Server Tester (https://www.metered.ca/turn-server-testing):

    • For Development/Testing (non-TLS):
      • TURN URL: YourServerPublicIP
      • TURN Port: 3478
      • Username: YourTurnUsername
      • Password: YourTurnPassword
    • For Production (TURNS) (if configured):
      • TURNS URL: turn.yourdomain
      • TURNS Port: 5349
      • Username: YourTurnUsername
      • Password: YourTurnPassword

    Look for "Success" or "Reachable" messages.

3.3. Nginx (Reverse Proxy - Production Environment)

Note: This section is entirely for production environments. If you are setting up a development or testing environment and not using Nginx as a reverse proxy, you can skip this entire Section 3.3.

It is recommended to use Nginx as a reverse proxy in production environments to handle SSL termination, serve static files (if applicable), and enable HTTP/3.

Installation (with HTTP/3 support, Ubuntu Example): Reference: https://nginx.org/en/linux_packages.html#Ubuntu

  1. Install prerequisites: 
    sudo apt install curl gnupg2 ca-certificates lsb-release ubuntu-keyring
  2. Import Nginx signing key: 
    curl https://nginx.org/keys/nginx_signing.key | gpg --dearmor \
 | sudo tee /usr/share/keyrings/nginx-archive-keyring.gpg >/dev/null
  3. Verify the key: 
    gpg --dry-run --quiet --no-keyring --import --import-options import-show /usr/share/keyrings/nginx-archive-keyring.gpg
# Expected fingerprint: 573BFD6B3D8FBC641079A6ABABF5BD827BD9BF62
  4. Set up the apt repository for stable Nginx packages: 
    echo "deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg] \
http://nginx.org/packages/ubuntu `lsb_release -cs` nginx" \
 | sudo tee /etc/apt/sources.list.d/nginx.list
  5. Set up repository pinning: 
    echo -e "Package: *\nPin: origin nginx.org\nPin: release o=nginx\nPin-Priority: 900\n" \
 | sudo tee /etc/apt/preferences.d/99nginx
  6. Install Nginx: 
    sudo apt update
sudo apt install nginx

Configuration (Production Environment):

  1. Firewall Configuration:

    • TCP 80 (for HTTP, redirects to HTTPS)
    • TCP 443 (for HTTPS)
    • UDP 443 (for HTTP/3 QUIC)
    sudo ufw allow 'Nginx Full' # Allows HTTP and HTTPS
sudo ufw allow 443/udp     # For HTTP/3
sudo ufw status

  2. Main Domain SSL Certificate: Obtain SSL certificates for your main application domain (e.g., yourdomain.com and www.yourdomain.com).

    # Ensure certbot is installed and configured to work with Nginx
sudo apt install python3-certbot-nginx
sudo certbot --nginx -d yourdomain.com -d www.yourdomain.com

    Follow the prompts. This will also attempt to configure Nginx for SSL.

  3. Nginx Configuration: docker/Nginx/default is an Nginx configuration template. You do not need to modify this file manually. Instead, add the following configuration to your production environment file .env.production.local:

    # Nginx Configuration (Production)
NGINX_SERVER_NAME=yourdomain # Without www prefix, yourdomain includes the suffix
NGINX_SSL_CERT=/etc/letsencrypt/live/yourdomain/fullchain.pem
NGINX_SSL_KEY=/etc/letsencrypt/live/yourdomain/privkey.pem
NGINX_FRONTEND_ROOT=/path/to/your/frontend/build # Path to your frontend static build artifacts

  4. Apply Nginx Configuration and Restart:

    # This script will use the NGINX_* variables from .env.production.local to generate the Nginx config file
sudo bash docker/Nginx/configure.sh .env.production.local

4. Backend Application Deployment

4.1. Get the Code

Clone your repository to the server:

git clone <your-repository-url> privydrop
cd privydrop/backend

4.2. Install Dependencies

npm install

4.3. Environment Variable Configuration

The backend application relies on environment variables to run. Create and configure the appropriate .env file in the privydrop/backend directory based on your deployment environment (development/testing or production).

  • Development/Testing Environment: Create an .env.development.local file.
  • Production Environment: Create an .env.production.local file. (Production Step)

Add the following basic backend-related configurations to the corresponding .env file:

NODE_ENV=development # or production
BACKEND_PORT=3001
CORS_ORIGIN=http://localhost:3000 # Development example, should be https://www.yourdomain for production

Important: Ensure that the Redis and TURN server related environment variables discussed in Section 3.1 (Redis) and Section 3.2 (TURN Server) have also been correctly added to the respective .env.development.local or .env.production.local file.

For the production environment (.env.production.local), make sure all configurations (e.g., NODE_ENV=production, production TURN URL, production CORS origin, etc.) are set correctly.

4.4. Start Development/Test Server

After completing the development environment configuration (.env.development.local), you can start the backend service for development or testing using the following command:

# Ensure you are in the privydrop/backend directory
npm run dev

This command typically uses the configuration from .env.development.local.

4.5. Production Deployment (Using PM2)

Note: This section describes how to deploy in a production environment using PM2. If you are only setting up a development/testing environment, you can skip this section.

PM2 is a production process manager for Node.js applications and is recommended for production deployments.

  1. Install PM2 globally:

    sudo npm install -g pm2

  2. Start the application using the ecosystem.config.js file: The backend/ecosystem.config.js file in the project root is the configuration file for PM2.

    # Ensure you are in the privydrop/backend directory
# cd /path/to/privydrop/backend

# Before starting, ensure .env.production.local is configured for production
sudo pm2 start ecosystem.config.js

    If you have a previously running instance with the same name (e.g., signaling-server defined in ecosystem.config.js):

    sudo pm2 stop signaling-server && sudo pm2 delete signaling-server
sudo pm2 start ecosystem.config.js

  3. Check application status and logs:

    sudo pm2 list
sudo pm2 logs signaling-server # Or the name defined in your ecosystem file
sudo pm2 monit

  4. Enable PM2 to start on boot:

    sudo pm2 startup
# Follow the instructions provided by the command (usually involves running another command it outputs)
sudo pm2 save # Save the current process list

5. Dockerized Deployment (Currently Not Fully Supported)

While this guide focuses on traditional deployment, you can also containerize the Privydrop backend. backend/docker/Dockerfile provides a record of the basic environment build process.

Note: This deployment method is currently mainly for reference, and official support is not yet complete. Docker deployment for production requires more detailed planning, including using docker-compose to orchestrate the backend application, Nginx (either within Docker or as a reverse proxy on the host), Redis, and potentially Coturn (although Coturn is often run directly on the host for better network access). Managing SSL certificates and network configurations in a Dockerized environment requires careful planning.

6. Security and Maintenance

  • SSL Certificate Renewal (Production Related): You can refer to the backend/docker/Nginx/renew_ssl.sh script for automatic renewal.
  • Firewall: Keep firewall rules strict, allowing only necessary ports.

7. Troubleshooting

  • Connection Issues: Check firewall rules, Nginx proxy settings (production), CORS_ORIGIN in the backend .env file, and ensure all services (Redis, Coturn, Node.js app) are running and configured correctly.
  • Nginx Errors (Production): sudo nginx -t will check configuration syntax. Check Nginx error logs (usually in /var/log/nginx/error.log).
  • PM2 Issues (Production): Use pm2 logs <app_name> to view application errors.
  • Certificate Permissions (Production): If Coturn or Nginx cannot read SSL certificates, double-check file permissions and user/group settings.
  • Coturn Logs: Check /var/log/turnserver.log (or the Coturn log path on your system) for Coturn service-related errors.
Reference in New Issue View Git Blame Copy Permalink