First

app/DEPLOYMENT.md

@@ -0,0 +1,336 @@
+# Deployment Guide
+
+This guide covers different deployment scenarios for the FRP Manager application.
+
+## Table of Contents
+1. [Docker Compose Deployment (Recommended)](#docker-compose-deployment)
+2. [Manual Deployment](#manual-deployment)
+3. [Development Setup](#development-setup)
+4. [Production Configuration](#production-configuration)
+5. [Troubleshooting](#troubleshooting)
+
+## Docker Compose Deployment
+
+### Prerequisites
+- Docker and Docker Compose installed
+- Access to your VPS/server running FRP server
+
+### Quick Start
+
+1. **Clone and Setup**
+   ```bash
+   git clone <repository-url>
+   cd frp-manager
+   ```
+
+2. **Configure Environment**
+   ```bash
+   cp .env.example .env
+   ```
+   
+   Edit `.env` with your FRP server details:
+   ```env
+   FRPC_SERVER_ADDR=your-vps-ip-address
+   FRPC_SERVER_PORT=7000
+   FRPC_TOKEN=your-secret-token
+   NODE_ENV=production
+   PORT=3000
+   ```
+
+3. **Deploy**
+   ```bash
+   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
+
+```bash
+# 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**
+   ```bash
+   npm install
+   ```
+
+2. **Build Application**
+   ```bash
+   npm run build
+   ```
+
+3. **Configure Environment**
+   ```bash
+   cp .env.example .env
+   # Edit .env with your configuration
+   ```
+
+4. **Create Directories**
+   ```bash
+   mkdir -p data logs
+   ```
+
+5. **Start Application**
+   ```bash
+   # Development
+   npm run dev
+   
+   # Production
+   npm start
+   ```
+
+### Process Management
+
+For production deployment, use a process manager like PM2:
+
+```bash
+# 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:
+
+```nginx
+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**
+   ```bash
+   npm install
+   ```
+
+2. **Create Environment File**
+   ```bash
+   cp .env.example .env
+   ```
+
+3. **Start Development Server**
+   ```bash
+   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
+
+```env
+# 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:
+```bash
+#!/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:
+
+```bash
+# 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:
+```bash
+# 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](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`