arc-frp/app/DEPLOYMENT.md

Deployment Guide

This guide covers different deployment scenarios for the FRP Manager application.

Table of Contents

1. Docker Compose Deployment (Recommended)
2. Manual Deployment
3. Development Setup
4. Production Configuration
5. Troubleshooting

Docker Compose Deployment

Prerequisites

• Docker and Docker Compose installed
• Access to your VPS/server running FRP server

Quick Start

1. Clone and Setup

   git clone <repository-url>
   cd frp-manager
   

2. Configure Environment

   cp .env.example .env
   

   Edit .env with your FRP server details:

   FRPC_SERVER_ADDR=your-vps-ip-address
   FRPC_SERVER_PORT=7000
   FRPC_TOKEN=your-secret-token
   NODE_ENV=production
   PORT=3000
   

3. Deploy

   docker-compose up -d
   

4. Access Application

   • Web Interface: http://localhost:3000
   • API: http://localhost:3000/api
   • Health Check: http://localhost:3000/health

Docker Compose Configuration

The docker-compose.yml includes:

• app: Main application container (Express API + React frontend)
• frpc: FRP client container for tunnel management

Key volumes:

• ./data:/app/data - Database and configuration files
• ./logs:/app/logs - Application logs
• /var/run/docker.sock:/var/run/docker.sock - Docker socket for container management

Updating the Application

# Pull latest changes
git pull origin main

# Rebuild and restart
docker-compose down
docker-compose up -d --build

Manual Deployment

Prerequisites

• Node.js 18+ installed
• Docker (for FRPC container)
• SQLite3

Installation Steps

1. Install Dependencies

   npm install
   

2. Build Application

   npm run build
   

3. Configure Environment

   cp .env.example .env
   # Edit .env with your configuration
   

4. Create Directories

   mkdir -p data logs
   

5. Start Application

   # Development
   npm run dev
   
   # Production
   npm start
   

Process Management

For production deployment, use a process manager like PM2:

# Install PM2
npm install -g pm2

# Start application with PM2
pm2 start npm --name "frp-manager" -- start

# Save PM2 configuration
pm2 save

# Setup auto-restart on reboot
pm2 startup

Reverse Proxy Setup

Example Nginx configuration:

server {
    listen 80;
    server_name your-domain.com;
    
    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
    }
}

Development Setup

Quick Start

1. Install Dependencies

   npm install
   

2. Create Environment File

   cp .env.example .env
   

3. Start Development Server

   npm run dev
   

Development Features

• Hot Reload: Both frontend and backend auto-reload on changes
• Debug Logging: Enhanced logging in development mode
• React DevTools: Included React Query DevTools
• Error Handling: Detailed error messages in development

Project Structure

app/
├── src/
│   ├── client/              # React frontend
│   │   ├── api/            # API client and types
│   │   ├── components/     # Reusable React components
│   │   ├── pages/          # Page components
│   │   └── App.tsx         # Main App component
│   └── server/             # Express backend
│       ├── database.ts     # SQLite database operations
│       ├── frpc-manager.ts # FRPC container management
│       ├── logger.ts       # Winston logging configuration
│       ├── main.ts         # Express server setup
│       ├── routes.ts       # API route definitions
│       └── types.ts        # TypeScript type definitions
├── public/                 # Static assets
├── data/                   # Database and FRPC config
├── logs/                   # Application logs
├── Dockerfile              # Docker container definition
├── docker-compose.yml      # Docker Compose configuration
└── package.json           # Project dependencies and scripts

Production Configuration

Environment Variables

# FRP Server Configuration
FRPC_SERVER_ADDR=your-vps-ip-address
FRPC_SERVER_PORT=7000
FRPC_TOKEN=your-secret-token

# Application Configuration
NODE_ENV=production
PORT=3000

# Security (optional)
CORS_ORIGIN=https://your-domain.com

Security Considerations

1. Authentication: Consider adding authentication for production use
2. CORS: Configure appropriate CORS settings
3. HTTPS: Use HTTPS in production
4. Firewall: Restrict access to necessary ports only
5. Docker Security: Run containers with non-root users

Monitoring

The application includes:

• Health Check Endpoint: /health
• Structured Logging: JSON logs with Winston
• Error Tracking: Comprehensive error logging
• Service Status: Built-in service monitoring

Backup Strategy

Important data to backup:

• Database: ./data/tunnels.db
• Configuration: ./data/frpc.toml
• Environment: .env
• Logs: ./logs/ (optional)

Example backup script:

#!/bin/bash
BACKUP_DIR="./backups/$(date +%Y%m%d_%H%M%S)"
mkdir -p "$BACKUP_DIR"
cp -r ./data "$BACKUP_DIR/"
cp .env "$BACKUP_DIR/"
tar -czf "$BACKUP_DIR.tar.gz" "$BACKUP_DIR"
rm -rf "$BACKUP_DIR"

Troubleshooting

Common Issues

Application Won't Start

• Check Node.js version (requires 18+)
• Verify all dependencies are installed
• Check port availability (default: 3000)
• Review logs in ./logs/error.log

Database Issues

• Ensure ./data directory exists and is writable
• Check SQLite permissions
• Verify database file integrity

FRPC Container Issues

• Verify Docker is running
• Check FRPC container logs: docker logs frpc
• Ensure FRPC configuration is valid
• Verify server connectivity

API Errors

• Check server logs for detailed error messages
• Verify API endpoints are accessible
• Check CORS configuration for frontend issues

Health Check Script

Use the provided health check script to verify all services:

# Linux/macOS
./health-check.sh

# Windows
powershell -ExecutionPolicy Bypass -File "health-check.ps1"

Log Analysis

Application logs are stored in ./logs/:

• combined.log: All application logs
• error.log: Error logs only

Example log analysis:

# View recent errors
tail -f ./logs/error.log

# Search for specific errors
grep "Failed to" ./logs/combined.log

# View API requests
grep "API Request" ./logs/combined.log

Support

For additional support:

1. Check the README.md file
2. Review application logs
3. Use the health check script
4. Open an issue on the repository

Performance Tuning

For high-traffic deployments:

1. Use a reverse proxy (Nginx, Apache)
2. Enable HTTP/2
3. Implement caching strategies
4. Monitor resource usage
5. Scale horizontally if needed

Updates and Maintenance

Regular maintenance tasks:

• Update dependencies: npm update
• Backup database regularly
• Monitor disk space for logs
• Review and rotate logs
• Update Docker images: docker-compose pull