aheh/PrivyDrop
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

update docs:add env_example in Tutorial;sync edit docs/DEPLOYMENT.md depend on docs/DEPLOYMENT.zh-CN.md.

Browse Source
This commit is contained in:
david_bai
2025-07-01 23:40:18 +08:00
parent 11b338432a
commit c9227baaf1
10 changed files with 202 additions and 200 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/DEPLOYMENT.md
+147 -117
View File
@@ -12,7 +12,7 @@ Before you begin, please ensure your server environment meets the following requ
- **Operating System:** A Linux distribution (e.g., Ubuntu 20.04 LTS or newer is recommended).
- **Node.js:** v18.x or higher.
- **npm (or yarn/pnpm):** The package manager for Node.js.
- **npm/pnpm:** The package manager for Node.js.
- **Root or Sudo Privileges:** Required for installing packages and configuring services.
- **Domain Name:** Required for a production deployment.
- **Optional: Base Environment & Docker Image Reference:** If you are starting from a very clean system environment or wish to see the base dependencies for a Docker build, you can refer to the `backend/docker/Dockerfile` (for Docker image creation) and `backend/docker/env_install.log` (dependency installation log) files.
@@ -32,7 +32,7 @@ sudo apt install redis-server
**Configuration:**
- By default, Redis listens on `127.0.0.1:6379` without a password. Ensure your backend's `.env` file includes the correct `REDIS_HOST` and `REDIS_PORT`.
- By default, Redis listens on `127.0.0.1:6379` without a password. Ensure your backend's `.env.production[development]` file includes the correct `REDIS_HOST` and `REDIS_PORT`.
- Verify that Redis is running: `sudo systemctl status redis-server`
- If it's not running, start it: `sudo systemctl start redis-server`
@@ -49,91 +49,23 @@ sudo apt update
sudo apt install coturn
```
**Configuration:**
**Base Configuration:**
1. **Enable the Coturn service:** Edit `/etc/default/coturn` and uncomment `TURNSERVER_ENABLED=1`.
2. **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) - **Production**.
- UDP `49152-65535`: Coturn's default relay port range.
1. **Enable the Coturn service:**
Edit `/etc/default/coturn` and uncomment `TURNSERVER_ENABLED=1`.
2. **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).
- UDP `49152-65535`: Coturn's default relay port range.
```bash
sudo ufw allow 3478
sudo ufw allow 5349
sudo ufw allow 49152:65535/udp
sudo ufw enable
sudo ufw reload # or ufw enable
```
3. **Production SSL Certificate (for TURNS):**
Obtain an SSL certificate for your TURN domain (e.g., `turn.yourdomain.com`).
```bash
# Ensure a DNS 'A' record points turn.yourdomain.com to your server's IP
sudo apt install certbot
sudo certbot certonly --standalone -d turn.yourdomain.com
```
4. **SSL Certificate Permissions:**
The Coturn process (usually runs as the `turnserver` user) needs permission to read the SSL certificate and private key.
- Check current permissions:
```bash
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:
```bash
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/`.
5. **Configure and Start Coturn:**
- Configure `TURN_*` related environment variables in the backend's `.env` file (e.g., username, password, certificate paths).
- For a **testing environment**, you need to set:
```
TURN_EXTERNAL_IP=YourServerPublicIP # e.g., 123.123.456.567
TURN_REALM=YourServerPublicIP
TURN_USERNAME=YourTurnUsername
TURN_PASSWORD=YourTurnPassword
```
- For a **production deployment**, you need to set:
```
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
```
- Use the script provided in the project to generate the configuration file and start the service:
```bash
# Located in the backend/ directory
sudo bash ./docker/TURN/configure.sh path/to/your/.env.production
# For a development environment, use .env.development
sudo systemctl status coturn
```
- Check the logs at `/var/log/turnserver.log` to confirm there are no errors.
6. **Online Testing (Optional):**
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):**
- TURNS URL: `turn.yourdomain.com`
- TURNS Port: `5349`
- Username: `YourTurnUsername`
- Password: `YourTurnPassword`
A successful test should show a "Reachable" message.
**Engineer's Note**: Detailed production configuration for Coturn (like SSL certificates, username, password, etc.) will be handled in `Section 4: Application Deployment` alongside Nginx and the main application to ensure a streamlined and unified process.
## 4. Application Deployment (Production)
@@ -142,8 +74,8 @@ This section describes how to deploy PrivyDrop in a production environment using
### 4.1. Get the Code and Install Dependencies
```bash
git clone <your-repository-url> privydrop
cd privydrop
git clone https://github.com/david-bai00/PrivyDrop.git
cd PrivyDrop
# Install backend dependencies
cd backend && npm install && cd ..
@@ -152,59 +84,152 @@ cd backend && npm install && cd ..
cd frontend && pnpm install && cd ..
```
### 4.2. Build the Frontend Application
### 4.2. Build the Application
```bash
cd frontend && pnpm build && cd ..
cd backend && npm build && cd ..
cd backend && npm run build && cd ..
```
This will generate an optimized production build in the `frontend/.next` and `backend/dist` directory.
This will generate an optimized production build in the `frontend/.next` and `backend/dist` directories.
### 4.3. Configure Nginx as a Reverse Proxy
In production, Nginx will act as the entry point for all traffic, handling SSL termination and routing requests to the correct frontend or backend service.
1. **Install Nginx:** It's recommended to install a newer version that supports HTTP/3.
1. **Prepare Production Environment Variables for Backend and Frontend**
Before deployment, ensure the production environment files for both backend and frontend are ready. You will need to copy them from the example files and modify them with your server's information.
2. **Firewall:** Ensure ports `TCP:80 (HTTP)` and `TCP/UDP:443 (HTTPS/HTTP3)` are open.
- **Backend Configuration:**
```bash
# From the project root
cp backend/.env_production_example backend/.env.production
```
Then, edit `backend/.env.production`, configuring at least `CORS_ORIGIN` to your main domain (e.g., `https://privydrop.app`) and your `REDIS` details.
3. **Main Domain SSL Certificate:** Obtain a certificate for your main domain (e.g., `yourdomain.com`).
- **Frontend Configuration:**
```bash
# From the project root
cp frontend/.env_production_example frontend/.env.production
```
Then, edit `frontend/.env.production` to set `NEXT_PUBLIC_API_URL` to your backend service domain (e.g., `https://privydrop.app`).
2. **Install Nginx:** It's recommended to install a newer version that supports HTTP/3.
3. **Firewall:** Ensure ports `TCP:80 (HTTP)` and `TCP/UDP:443 (HTTPS/HTTP3)` are open.
4. **Generate Base Nginx Configuration:**
The `backend/docker/Nginx/` directory provides a configuration script and template. This template uses a temporary "placeholder" certificate to ensure the Nginx configuration is valid before obtaining a real certificate.
- Now, edit the `backend/.env.production` file and add the `NGINX_*` related variables. **Do not include SSL certificate paths yet**. Example:
```
NGINX_SERVER_NAME=privydrop.app # Your main domain
NGINX_FRONTEND_ROOT=/path/to/your/PrivyDrop/frontend # Path to the frontend project root
```
- Execute the script to generate the Nginx configuration file:
```bash
# This script uses variables from your .env file to generate the Nginx config
sudo bash backend/docker/Nginx/configure.sh backend/.env.production
```
### 4.4. Use Certbot to Install a Unified SSL Certificate
With the base Nginx configuration in place, we can now use Certbot to obtain and install a real SSL certificate. We will request a single, unified certificate for all our services (main domain, www, and TURN) and let Certbot automatically update our Nginx configuration.
1. **Install Certbot's Nginx Plugin:**
```bash
sudo apt install python3-certbot-nginx
sudo certbot --nginx -d yourdomain.com -d www.yourdomain.com
```
4. **Nginx Configuration File:**
The `backend/docker/Nginx/` directory in the project provides a configuration script and template.
2. **Run Certbot to Request the Certificate:**
- This command automatically detects your Nginx configuration.
- The `-d` flag specifies all domains to be included in the certificate. Ensure your domains' DNS records correctly point to your server's IP.
- The `--deploy-hook` is a crucial parameter: it will automatically restart the Coturn service after a successful certificate renewal, applying the new certificate. This enables fully automated certificate maintenance.
- Add the `NGINX_*` related variables to your backend's `.env.production` file, including the domain, certificate paths, and the **root directory of the frontend build artifacts**. Example:
```
NGINX_SERVER_NAME=yourdomain.com # The full domain name
NGINX_SSL_CERT=/etc/letsencrypt/live/yourdomain.com/fullchain.pem
NGINX_SSL_KEY=/etc/letsencrypt/live/yourdomain.com/privkey.pem
NGINX_FRONTEND_ROOT=/path/to/your/frontend/.next # Path to frontend build output
```
5. **Apply Configuration:** Generate the Nginx config, create a symbolic link, and restart Nginx.
```bash
# This script uses NGINX_* variables from your .env file to generate the Nginx config
sudo bash backend/docker/Nginx/configure.sh backend/.env.production
# Replace privydrop.app with your main domain
sudo certbot --nginx \
-d privydrop.app \
-d www.privydrop.app \
-d turn.privydrop.app \
--deploy-hook "sudo systemctl restart coturn"
```
Follow the on-screen prompts from Certbot (e.g., enter your email, agree to the ToS). Once complete, Certbot will automatically modify your Nginx configuration to enable HTTPS and reload the Nginx service.
3. **Verification and Troubleshooting (Important):**
First, verify that the certificate path in your Nginx configuration has been updated automatically.
```bash
sudo grep ssl_certificate /etc/nginx/sites-available/default
```
You should see a path pointing to `/etc/letsencrypt/live/privydrop.app/`.
If, after running `certbot --nginx`, the path still points to the old placeholder, run the following command to force the certificate installation:
```bash
sudo certbot install --cert-name privydrop.app -d privydrop.app -d www.privydrop.app -d turn.privydrop.app
# Then, reload Nginx to apply the changes
sudo systemctl reload nginx
```
### 4.4. Configure Environment Variables
### 4.5. Configure and Start the TURN Service (Production)
- **Backend:**
- Create a `.env.production` file in the `backend/` directory.
- Fill in the necessary environment variables (e.g., `BACKEND_PORT`, `REDIS_HOST`, `REDIS_PORT`, `CORS_ORIGIN`).
- For Nginx integration, also add `NGINX_SERVER_NAME`, `NGINX_SSL_CERT`, `NGINX_SSL_KEY`, and `NGINX_FRONTEND_ROOT`.
- **Frontend:**
- Create a `.env.production` file in the `frontend/` directory.
- Fill in the `NEXT_PUBLIC_API_URL` variable.
With the unified SSL certificate obtained, we can now complete the production configuration for the Coturn service.
### 4.5. Run the Application with PM2
1. **Configure Environment Variables**:
Open your `backend/.env.production` file and configure all `TURN_*` related variables.
```ini
# .env.production
# ... other variables ...
# TURN/STUN Server (Coturn) Configuration
TURN_REALM=turn.privydrop.app # Your TURN domain
TURN_USERNAME=YourTurnUsername # Set a secure username
TURN_PASSWORD=YourTurnPassword # Set a strong password
# Critical: Point to the unified certificate generated by Certbot for your main domain
TURN_CERT_PATH=/etc/letsencrypt/live/privydrop.app/fullchain.pem
TURN_KEY_PATH=/etc/letsencrypt/live/privydrop.app/privkey.pem
```
2. **Verify SSL Certificate Permissions**:
The Coturn process typically runs as a low-privilege user (e.g., `turnserver` or `coturn`), while certificates generated by Certbot are owned by `root`. We need to adjust permissions to allow Coturn to read the certificate.
```bash
# (Optional) Find the user the coturn service runs as
# ps aux | grep turnserver
# Create a shared group and add the turnserver user to it
sudo groupadd -f ssl-cert
sudo usermod -a -G ssl-cert turnserver # Replace 'turnserver' if the user is different
# Change ownership and permissions of the certificate directories
sudo chown -R root:ssl-cert /etc/letsencrypt/
sudo chmod -R 750 /etc/letsencrypt/
```
3. **Generate Configuration File and Start the Service**:
Run the provided script, which will generate `/etc/turnserver.conf` from your `.env.production` file and restart Coturn.
```bash
# Located in the backend/ directory
# Use the path to your .env file
sudo bash ./docker/TURN/configure.sh backend/.env.production
```
4. **Check Service Status and Test Online**:
- Check the service status:
```bash
sudo systemctl status coturn
# Also, check the logs to ensure there are no permission errors
# sudo journalctl -u coturn -f
```
- **Online Test (Recommended)**:
Once the service is running, use an online tool like the [Metered TURN Server Tester](https://www.metered.ca/turn-server-testing) to verify that your TURNS service is working correctly:
- **TURNS URL**: `turns:turn.privydrop.app:5349` (replace with your domain)
- **Username**: `The username you set in your .env file`
- **Password**: `The password you set in your .env file`
If all checkpoints show a green "Success" or "Reachable", your TURN server is configured successfully.
### 4.6. Run the Application with PM2
PM2 is a powerful process manager for Node.js. We will use it to run the backend and frontend services separately.
@@ -219,15 +244,20 @@ PM2 is a powerful process manager for Node.js. We will use it to run the backend
```bash
cd backend
# If previously run, execute this first
sudo pm2 stop signaling-server && sudo pm2 delete signaling-server
# Ensure .env.production is fully configured
pm2 start ecosystem.config.js
sudo pm2 start ecosystem.config.js
```
3. **Start the Frontend Service:**
```bash
cd frontend
pm2 start npm --name "privydrop-frontend" -- run start
# If previously run, execute this first
sudo pm2 stop privydrop-frontend && sudo pm2 delete privydrop-frontend
sudo pm2 start npm --name "privydrop-frontend" -- run start
```
The `npm start` command starts the Next.js production server, which listens on port 3000 by default.
@@ -242,9 +272,9 @@ PM2 is a powerful process manager for Node.js. We will use it to run the backend
- **Connection Issues:** Check firewall settings, Nginx proxy configurations, `CORS_ORIGIN` settings, and ensure all PM2 processes are running.
- **Nginx Errors:** Use `sudo nginx -t` to check syntax and review `/var/log/nginx/error.log`.
- **PM2 Issues:** Use `pm2 logs <app_name>` to view application logs.
- **Certificate Permissions (Production):** If Coturn or Nginx cannot read SSL certificates, carefully check file permissions and user/group settings.
- **Certificate Permissions (Production):** If Coturn or Nginx cannot read SSL certificates, carefully review the file permissions and user/group settings in `Section 4.5`.
## 6. Security & Maintenance
- **SSL Certificate Renewal (Production):** You can refer to the `backend/docker/Nginx/renew_ssl.sh` script to automate renewal.
- **SSL Certificate Renewal:** When you successfully configure your certificate using `certbot --nginx` with the `--deploy-hook`, Certbot automatically creates a renewal task for both Nginx and Coturn. No manual intervention is required; the certificate will be renewed and applied automatically before it expires.
- **Firewall:** Maintain strict firewall rules, only allowing necessary ports.
docs/DEPLOYMENT.zh-CN.md
+23 -6
View File
@@ -97,14 +97,31 @@ cd backend && npm run build && cd ..
在生产中，Nginx 将作为所有流量的入口，负责 SSL 终止，并将请求路由到正确的前端或后端服务。
1. **安装 Nginx:** 推荐安装支持 HTTP/3 的较新版本。
1. **为后端和前端准备生产环境变量**
在部署之前，请确保后端和前端的生产环境变量文件已准备就绪。您需要从示例文件复制并根据您的服务器信息进行修改。
2. **防火墙:** 确保 `TCP:80 (HTTP)` 和 `TCP/UDP:443 (HTTPS/HTTP3)` 端口已打开。
- **后端配置:**
```bash
# 位于项目根目录
cp backend/.env_production_example backend/.env.production
```
然后编辑 `backend/.env.production`，至少配置 `CORS_ORIGIN` 为您的主域名 (例如 `https://privydrop.app`) 以及 `REDIS` 相关信息。
3. **生成 Nginx 基础配置:**
后端项目 `backend/docker/Nginx/` 目录中提供了配置脚本和模板。此模板使用一个临时的“占位符”证书，以确保 Nginx 配置在申请真实证书前是有效的。
- **前端配置:**
```bash
# 位于项目根目录
cp frontend/.env_production_example frontend/.env.production
```
然后编辑 `frontend/.env.production`，配置 `NEXT_PUBLIC_API_URL` 为您的后端服务域名 (例如 `https://privydrop.app`)。
- 在后端的 `.env.production` 文件中添加 `NGINX_*` 相关变量，**无需 SSL 证书路径**。示例为：
2. **安装 Nginx:** 推荐安装支持 HTTP/3 的较新版本。
3. **防火墙:** 确保 `TCP:80 (HTTP)` 和 `TCP/UDP:443 (HTTPS/HTTP3)` 端口已打开。
4. **生成 Nginx 基础配置:**
后端项目 `backend/docker/Nginx/` 目录中提供了配置脚本和模板。此模板使用一个临时的"占位符"证书，以确保 Nginx 配置在申请真实证书前是有效的。
- 现在，编辑 `backend/.env.production` 文件，添加 `NGINX_*` 相关变量。**无需 SSL 证书路径**。示例为：
```
NGINX_SERVER_NAME=privydrop.app # 你的主域名
NGINX_FRONTEND_ROOT=/path/to/your/PrivyDrop/frontend # 前端项目根目录
@@ -158,7 +175,7 @@ cd backend && npm run build && cd ..
获取到统一的 SSL 证书后，我们现在来完成 Coturn 服务的生产环境配置。
1. **配置环境变量**:
在后端的 `.env.production` 文件中，配置所有 `TURN_*` 相关变量。
打开后端的 `.env.production` 文件，配置所有 `TURN_*` 相关变量。
```ini
# .env.production