First

NODE_INTEGRATION.md

@@ -0,0 +1,229 @@
+# 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.