arc-frp/NODE_INTEGRATION.md

# FRP Manager - Node Integration Setup

This guide explains how to set up the integration between the FRP Manager app and the home server node.

## Overview

The integration allows the FRP Manager app (running on your VPS) to:
- Query the home server node for status
- Send updated frpc.toml configurations
- Restart the FRP client remotely
- Monitor node connectivity

## Setup Instructions

### 1. Environment Configuration

#### App (.env file)
```bash
# Copy from .env.example and configure these variables:

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

# Node Integration
NODE_URL=http://your-home-server-ip:3001
NODE_TOKEN=your-node-secret-token
NODE_TIMEOUT=5000
```

#### Node (.env file)
```bash
# Copy from .env.example and configure these variables:

# Authentication
API_TOKEN=your-node-secret-token

# FRP Configuration
FRPC_CONFIG_PATH=/app/data/frpc.toml
FRPC_CONTAINER_NAME=frpc
```

### 2. Security Considerations

**Important**: Use the same token for `NODE_TOKEN` in the app and `API_TOKEN` in the node for authentication.

- Generate a strong, random token (e.g., 32+ character string)
- Keep tokens secure and never commit them to version control
- Use HTTPS in production for encrypted communication

### 3. Network Setup

#### Port Configuration
- **App**: Runs on port 3000 (configurable)
- **Node**: Runs on port 3001 (configurable)

#### Firewall Rules
Ensure the node port (3001) is accessible from your VPS:
```bash
# On your home server (if using UFW)
sudo ufw allow 3001/tcp
```

#### Network Access
- The app needs HTTP/HTTPS access to the node
- Consider using a VPN or port forwarding if the node is behind NAT
- For production, use HTTPS with proper certificates

### 4. Docker Deployment

#### Starting the App (VPS)
```bash
cd app/
cp .env.example .env
# Edit .env with your configuration
docker-compose up -d
```

#### Starting the Node (Home Server)
```bash
cd node/
cp .env.example .env
# Edit .env with your configuration
docker-compose up -d
```

### 5. API Endpoints

#### Node Endpoints (Protected by API_TOKEN)
- `GET /api/status` - Get server status
- `GET /api/frpc/status` - Get frpc container status
- `POST /api/frpc/update-config` - Update frpc configuration
- `POST /api/frpc/restart` - Restart frpc container
- `POST /api/frpc/push-and-restart` - Update config and restart in one call

#### App Endpoints (Node Integration)
- `GET /api/node/status` - Get node status through app
- `GET /api/node/connection` - Get node connection info
- `POST /api/node/push-config` - Push current config to node
- `POST /api/node/restart-frpc` - Restart frpc on node
- `POST /api/node/push-and-restart` - Push config and restart frpc on node

### 6. Frontend Features

#### Dashboard
- Live node status indicator
- Connection monitoring
- Last connection time tracking

#### Tunnel Manager
- "Push to Node" button for deploying configurations
- Real-time node connectivity status
- Error handling and user feedback

### 7. Testing the Integration

#### 1. Verify Node Connectivity
```bash
# From your VPS, test the node endpoint
curl -H "Authorization: Bearer your-node-secret-token" \
     http://your-home-server-ip:3001/health
```

#### 2. Test Configuration Push
1. Create/modify tunnels in the app
2. Click "Push to Node" button
3. Verify configuration updated on the node
4. Check that frpc restarted successfully

#### 3. Monitor Logs
```bash
# App logs
docker logs frp-manager

# Node logs
docker logs home-server-agent

# FRP client logs
docker logs frpc
```

### 8. Troubleshooting

#### Common Issues

**"Node client not configured"**
- Check that `NODE_URL` and `NODE_TOKEN` are set in app environment
- Verify environment variables are loaded correctly

**"Failed to connect to node"**
- Verify node is running and accessible
- Check firewall rules
- Ensure correct IP address and port
- Verify token authentication

**"frpc container not found"**
- Ensure frpc container exists with the correct name
- Check `FRPC_CONTAINER_NAME` environment variable
- Verify Docker is accessible from the node

#### Debugging Steps

1. **Check Environment Variables**
   ```bash
   # In app container
   docker exec frp-manager env | grep NODE_

   # In node container
   docker exec home-server-agent env | grep API_TOKEN
   ```

2. **Test Direct API Calls**
   ```bash
   # Test node health endpoint (no auth required)
   curl http://your-home-server-ip:3001/health

   # Test authenticated endpoint
   curl -H "Authorization: Bearer your-token" \
        http://your-home-server-ip:3001/api/status
   ```

3. **Check Container Status**
   ```bash
   # On home server
   docker ps | grep frpc
   docker logs frpc
   ```

### 9. Production Considerations

#### Security
- Use HTTPS with valid certificates
- Implement IP whitelisting if possible
- Regular token rotation
- Monitor authentication logs

#### Monitoring
- Set up health checks for both app and node
- Monitor node connectivity from app
- Log all configuration changes
- Set up alerts for connection failures

#### Backup
- Backup frpc configurations
- Backup tunnel database
- Document recovery procedures

## Usage Examples

### Deploying New Tunnel Configuration

1. **Add/Edit Tunnels**: Use the web interface to create or modify tunnel configurations
2. **Push to Node**: Click the "Push to Node" button in the Tunnel Manager
3. **Verify**: Check the dashboard for node status and tunnel activity

### Manual Configuration Management

```bash
# Push configuration via API
curl -X POST -H "Authorization: Bearer app-token" \
     http://your-vps:3000/api/node/push-config

# Restart frpc on node
curl -X POST -H "Authorization: Bearer app-token" \
     http://your-vps:3000/api/node/restart-frpc
```

This integration provides a seamless way to manage FRP configurations across your infrastructure while maintaining security and monitoring capabilities.