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)](#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`