Feat : Gitbook

gitbook/content/en/deployment/cloud.md

@@ -0,0 +1,473 @@
+# ☁️ Cloud Deployment
+
+Deploy 9Router on VPS or Docker for remote access and production use.
+
+---
+
+## 🖥️ VPS Deployment
+
+### Prerequisites
+
+- Ubuntu 20.04+ or similar Linux distribution
+- Node.js 20+
+- Git
+- Root or sudo access
+
+### Step 1: Clone Repository
+
+```bash
+git clone https://github.com/decolua/9router.git
+cd 9router/app
+```
+
+### Step 2: Install Dependencies
+
+```bash
+npm install
+```
+
+### Step 3: Build Application
+
+```bash
+npm run build
+```
+
+### Step 4: Configure Environment Variables
+
+Create a `.env` file or export variables:
+
+```bash
+export JWT_SECRET="your-secure-secret-change-this-to-random-string"
+export INITIAL_PASSWORD="your-secure-password"
+export DATA_DIR="/var/lib/9router"
+export NODE_ENV="production"
+```
+
+**Environment Variables:**
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `JWT_SECRET` | Auto-generated | **MUST change in production!** Used for JWT token signing |
+| `INITIAL_PASSWORD` | `123456` | Dashboard login password |
+| `DATA_DIR` | `~/.9router` | Database and data storage path |
+| `NODE_ENV` | `development` | Set to `production` for deployment |
+| `ENABLE_REQUEST_LOGS` | `false` | Enable debug request/response logs |
+
+### Step 5: Create Data Directory
+
+```bash
+sudo mkdir -p /var/lib/9router
+sudo chown $USER:$USER /var/lib/9router
+```
+
+### Step 6: Start Application
+
+```bash
+npm run start
+```
+
+### Step 7: Setup PM2 for Production
+
+PM2 keeps your application running and restarts it on crashes:
+
+```bash
+# Install PM2 globally
+npm install -g pm2
+
+# Start 9Router with PM2
+pm2 start npm --name 9router -- start
+
+# Save PM2 configuration
+pm2 save
+
+# Setup PM2 to start on system boot
+pm2 startup
+# Follow the instructions printed by the command above
+```
+
+**PM2 Management Commands:**
+
+```bash
+# View logs
+pm2 logs 9router
+
+# Restart application
+pm2 restart 9router
+
+# Stop application
+pm2 stop 9router
+
+# View status
+pm2 status
+
+# Monitor resources
+pm2 monit
+```
+
+---
+
+## 🐳 Docker Deployment
+
+### Option 1: Using Dockerfile
+
+Create a `Dockerfile` in the `app` directory:
+
+```dockerfile
+FROM node:20-alpine
+
+WORKDIR /app
+
+# Copy package files
+COPY package*.json ./
+
+# Install dependencies
+RUN npm ci --only=production
+
+# Copy application files
+COPY . .
+
+# Build application
+RUN npm run build
+
+# Expose ports
+EXPOSE 3000 20128
+
+# Set environment variables
+ENV NODE_ENV=production
+ENV DATA_DIR=/app/data
+
+# Create data directory
+RUN mkdir -p /app/data
+
+# Start application
+CMD ["npm", "run", "start"]
+```
+
+**Build and Run:**
+
+```bash
+# Build image
+docker build -t 9router .
+
+# Run container
+docker run -d \
+  --name 9router \
+  -p 3000:3000 \
+  -p 20128:20128 \
+  -e JWT_SECRET="your-secure-secret-change-this" \
+  -e INITIAL_PASSWORD="your-secure-password" \
+  -v 9router-data:/app/data \
+  9router
+```
+
+### Option 2: Docker Compose
+
+Create `docker-compose.yml`:
+
+```yaml
+version: '3.8'
+
+services:
+  9router:
+    build: .
+    container_name: 9router
+    ports:
+      - "3000:3000"
+      - "20128:20128"
+    environment:
+      - NODE_ENV=production
+      - JWT_SECRET=your-secure-secret-change-this
+      - INITIAL_PASSWORD=your-secure-password
+      - DATA_DIR=/app/data
+    volumes:
+      - 9router-data:/app/data
+    restart: unless-stopped
+
+volumes:
+  9router-data:
+```
+
+**Run with Docker Compose:**
+
+```bash
+# Start services
+docker-compose up -d
+
+# View logs
+docker-compose logs -f
+
+# Stop services
+docker-compose down
+
+# Rebuild and restart
+docker-compose up -d --build
+```
+
+---
+
+## 🌐 Reverse Proxy with Nginx
+
+### Why Use Nginx?
+
+- SSL/TLS termination
+- Domain name mapping
+- Load balancing
+- Better security
+
+### Step 1: Install Nginx
+
+```bash
+sudo apt update
+sudo apt install nginx
+```
+
+### Step 2: Configure Nginx
+
+Create `/etc/nginx/sites-available/9router`:
+
+```nginx
+server {
+    listen 80;
+    server_name your-domain.com;
+
+    # Redirect HTTP to HTTPS
+    return 301 https://$server_name$request_uri;
+}
+
+server {
+    listen 443 ssl http2;
+    server_name your-domain.com;
+
+    # SSL certificates (use certbot to generate)
+    ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;
+
+    # SSL configuration
+    ssl_protocols TLSv1.2 TLSv1.3;
+    ssl_ciphers HIGH:!aNULL:!MD5;
+    ssl_prefer_server_ciphers on;
+
+    # Proxy to 9Router
+    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;
+        
+        # SSE support - CRITICAL for streaming
+        proxy_buffering off;
+        proxy_read_timeout 86400;
+    }
+
+    # API endpoint
+    location /v1 {
+        proxy_pass http://localhost:20128;
+        proxy_http_version 1.1;
+        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;
+        
+        # SSE support - CRITICAL for streaming
+        proxy_buffering off;
+        proxy_read_timeout 86400;
+    }
+}
+```
+
+### Step 3: Enable Site
+
+```bash
+# Create symbolic link
+sudo ln -s /etc/nginx/sites-available/9router /etc/nginx/sites-enabled/
+
+# Test configuration
+sudo nginx -t
+
+# Reload Nginx
+sudo systemctl reload nginx
+```
+
+### Step 4: Setup SSL with Let's Encrypt
+
+```bash
+# Install certbot
+sudo apt install certbot python3-certbot-nginx
+
+# Obtain SSL certificate
+sudo certbot --nginx -d your-domain.com
+
+# Auto-renewal is configured automatically
+# Test renewal
+sudo certbot renew --dry-run
+```
+
+---
+
+## 🔒 Security Considerations
+
+### 1. Change Default Credentials
+
+**CRITICAL:** Change `JWT_SECRET` and `INITIAL_PASSWORD` before deployment:
+
+```bash
+# Generate secure JWT secret
+openssl rand -base64 32
+
+# Use this value for JWT_SECRET
+export JWT_SECRET="generated-secret-here"
+```
+
+### 2. Firewall Configuration
+
+```bash
+# Allow SSH
+sudo ufw allow 22/tcp
+
+# Allow HTTP/HTTPS (if using Nginx)
+sudo ufw allow 80/tcp
+sudo ufw allow 443/tcp
+
+# If NOT using reverse proxy, allow 9Router ports
+sudo ufw allow 3000/tcp
+sudo ufw allow 20128/tcp
+
+# Enable firewall
+sudo ufw enable
+```
+
+### 3. Restrict Dashboard Access
+
+If you only need API access, restrict dashboard port:
+
+```bash
+# Only allow localhost access to dashboard
+sudo ufw deny 3000/tcp
+```
+
+Access dashboard via SSH tunnel:
+
+```bash
+ssh -L 3000:localhost:3000 user@your-server.com
+# Then open http://localhost:3000 in your browser
+```
+
+### 4. Regular Updates
+
+```bash
+# Update system packages
+sudo apt update && sudo apt upgrade -y
+
+# Update 9Router
+cd /path/to/9router/app
+git pull
+npm install
+npm run build
+pm2 restart 9router
+```
+
+### 5. Backup Strategy
+
+```bash
+# Backup data directory
+tar -czf 9router-backup-$(date +%Y%m%d).tar.gz /var/lib/9router
+
+# Automated daily backup (add to crontab)
+0 2 * * * tar -czf /backups/9router-$(date +\%Y\%m\%d).tar.gz /var/lib/9router
+```
+
+---
+
+## 📊 Monitoring
+
+### Check Application Status
+
+```bash
+# PM2 status
+pm2 status
+
+# View logs
+pm2 logs 9router --lines 100
+
+# Monitor resources
+pm2 monit
+```
+
+### Nginx Logs
+
+```bash
+# Access logs
+sudo tail -f /var/log/nginx/access.log
+
+# Error logs
+sudo tail -f /var/log/nginx/error.log
+```
+
+### System Resources
+
+```bash
+# CPU and memory usage
+htop
+
+# Disk usage
+df -h
+
+# Network connections
+netstat -tulpn | grep -E '3000|20128'
+```
+
+---
+
+## 🚨 Troubleshooting
+
+### Application Won't Start
+
+```bash
+# Check logs
+pm2 logs 9router
+
+# Check if ports are in use
+sudo lsof -i :3000
+sudo lsof -i :20128
+
+# Check environment variables
+pm2 env 9router
+```
+
+### Nginx 502 Bad Gateway
+
+```bash
+# Check if 9Router is running
+pm2 status
+
+# Check Nginx error logs
+sudo tail -f /var/log/nginx/error.log
+
+# Test Nginx configuration
+sudo nginx -t
+```
+
+### SSE Streaming Not Working
+
+Ensure `proxy_buffering off` is set in Nginx configuration for SSE support.
+
+### Permission Denied Errors
+
+```bash
+# Fix data directory permissions
+sudo chown -R $USER:$USER /var/lib/9router
+chmod 755 /var/lib/9router
+```
+
+---
+
+## 🔗 Next Steps
+
+- [Connect Providers](/providers/subscription.md)
+- [Setup Combos](/features/combos.md)
+- [Integrate with Tools](/integration/cursor.md)

gitbook/content/en/deployment/localhost.md

@@ -0,0 +1,164 @@
+# 🏠 Localhost Deployment
+
+Run 9Router on your local machine for development and personal use.
+
+---
+
+## 📦 Installation
+
+Install 9Router globally via npm:
+
+```bash
+npm install -g 9router
+```
+
+**Requirements:**
+- Node.js 20 or higher
+- npm 9 or higher
+
+---
+
+## 🚀 Starting the Server
+
+Start 9Router with a single command:
+
+```bash
+9router
+```
+
+The dashboard will automatically open in your browser at `http://localhost:3000`
+
+**Default Configuration:**
+- **Dashboard**: `http://localhost:3000`
+- **API Endpoint**: `http://localhost:20128/v1`
+- **Data Directory**: `~/.9router`
+
+---
+
+## 🔧 Configuration
+
+### Custom Data Directory
+
+Set a custom data directory using environment variable:
+
+```bash
+DATA_DIR=/path/to/data 9router
+```
+
+### Custom Port
+
+The API port (20128) and dashboard port (3000) are configured in the application. To change them, you'll need to modify the source code or use environment variables if supported.
+
+---
+
+## 🛑 Stopping the Server
+
+Press `Ctrl+C` in the terminal where 9Router is running.
+
+```bash
+# In the terminal running 9router
+^C  # Press Ctrl+C
+```
+
+The server will gracefully shut down and save all data.
+
+---
+
+## 🔄 Restarting the Server
+
+Simply run the start command again:
+
+```bash
+9router
+```
+
+All your configurations, API keys, and combos are preserved in the data directory.
+
+---
+
+## 📊 Updating 9Router
+
+Update to the latest version:
+
+```bash
+npm update -g 9router
+```
+
+Check your current version:
+
+```bash
+npm list -g 9router
+```
+
+---
+
+## 🔍 Troubleshooting
+
+### Port Already in Use
+
+If port 20128 or 3000 is already in use:
+
+```bash
+# Find process using the port (macOS/Linux)
+lsof -i :20128
+lsof -i :3000
+
+# Kill the process
+kill -9 <PID>
+```
+
+### Permission Errors
+
+If you encounter permission errors during installation:
+
+```bash
+# Use sudo (not recommended)
+sudo npm install -g 9router
+
+# Or fix npm permissions (recommended)
+mkdir ~/.npm-global
+npm config set prefix '~/.npm-global'
+echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
+source ~/.bashrc
+```
+
+### Data Directory Issues
+
+If the data directory is not accessible:
+
+```bash
+# Check permissions
+ls -la ~/.9router
+
+# Fix permissions
+chmod 755 ~/.9router
+```
+
+---
+
+## 📁 Data Directory Structure
+
+```
+~/.9router/
+├── db.json           # Main database (providers, combos, settings)
+├── logs/             # Application logs
+└── cache/            # Temporary cache files
+```
+
+**Backup Your Data:**
+
+```bash
+# Backup
+cp -r ~/.9router ~/.9router.backup
+
+# Restore
+cp -r ~/.9router.backup ~/.9router
+```
+
+---
+
+## 🔗 Next Steps
+
+- [Connect Providers](/providers/subscription.md)
+- [Create Combos](/features/combos.md)
+- [Integrate with CLI Tools](/integration/cursor.md)