fleetcode/WEB_SERVER_SETUP.md

182 lines
4 KiB
Markdown

# FleetCode Web Server Setup
FleetCode can run as a web server, making it accessible from any device on your network or over the internet.
## Quick Start
```bash
# Enter Nix development shell
nix develop
# Install dependencies (first time only)
npm install
# Start the web server
npm run server
```
The server will start on `http://0.0.0.0:3000` by default.
## Accessing the Server
### Local Access
Open your browser and navigate to:
```
http://localhost:3000
```
### Network Access
From other devices on your network:
```
http://<your-machine-ip>:3000
```
To find your IP address:
```bash
# On Linux
ip addr show | grep "inet "
# Or
hostname -I
```
### Remote Access (Internet)
To access FleetCode over the internet, you have several options:
#### Option 1: Port Forwarding (if you control your router)
1. Forward port 3000 on your router to your machine
2. Access via your public IP: `http://<your-public-ip>:3000`
3. **Important**: Add authentication/security before exposing to internet
#### Option 2: Tailscale/ZeroTier (recommended for security)
1. Install Tailscale or ZeroTier on your machine
2. Access via your Tailscale/ZeroTier IP from any device on your network
#### Option 3: Reverse Proxy (nginx/caddy + Let's Encrypt)
Set up a reverse proxy with HTTPS for secure access
## Custom Port
To use a different port:
```bash
PORT=8080 npm run server
```
## Architecture
The web server version uses:
- **Express** - HTTP server
- **Socket.IO** - Real-time bidirectional communication
- **node-pty** - Terminal emulation
- **xterm.js** - Terminal UI in the browser
The same `index.html` and terminal logic works for both:
- **Web mode**: Uses Socket.IO instead of Electron IPC
- **Desktop mode**: Uses Electron IPC for communication
## Development
### Running the Server
```bash
npm run server # Build and start
npm run dev:server # Same as above
```
### Building Only
```bash
npm run build # Build TypeScript and CSS
```
### File Structure
```
FleetCode/
├── server.ts # Web server (Express + Socket.IO)
├── main.ts # Electron main process
├── renderer.ts # Browser/renderer code
├── index.html # UI (works for both modes)
├── dist/
│ ├── server.js # Compiled web server
│ ├── main.js # Compiled Electron main
│ └── styles.css # Compiled Tailwind CSS
```
## Security Considerations
⚠️ **Important**: The default setup has no authentication!
Before exposing to the internet:
1. **Add Authentication**
- Implement user login
- Use session tokens
- Consider OAuth/OIDC
2. **Use HTTPS**
- Set up reverse proxy (nginx/caddy)
- Get SSL certificate (Let's Encrypt)
3. **Firewall Rules**
- Only allow specific IPs if possible
- Use VPN for remote access
4. **Environment Variables**
- Don't commit secrets
- Use `.env` files (not tracked in git)
## Troubleshooting
### Port Already in Use
```bash
# Find what's using the port
sudo lsof -i :3000
# Use a different port
PORT=8080 npm run server
```
### Cannot Connect from Network
1. Check firewall:
```bash
# On NixOS, check firewall status
sudo iptables -L
# Allow port temporarily
sudo iptables -A INPUT -p tcp --dport 3000 -j ACCEPT
```
2. Verify server is listening on 0.0.0.0 (not 127.0.0.1)
### Native Module Errors
If you see errors about `node-pty`:
```bash
# Rebuild for Node.js (not Electron)
npm rebuild node-pty --update-binary
```
## Comparison: Web Server vs Desktop App
| Feature | Web Server | Desktop App |
|---------|------------|-------------|
| Remote Access | ✅ Yes | ❌ No |
| Installation | Browser only | Electron required |
| Performance | Network dependent | Native speed |
| Multi-user | Possible (with auth) | Single user |
| Setup | Simple | More complex |
## Next Steps
1. **Add Authentication**: Implement user login system
2. **HTTPS Setup**: Configure reverse proxy with SSL
3. **Multi-user Support**: Session isolation per user
4. **Monitoring**: Add logging and metrics
5. **Docker**: Containerize for easy deployment