fleetcode/WEB_SERVER_SETUP.md

4 KiB

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

# 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:

# 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
  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:

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

npm run server        # Build and start
npm run dev:server    # Same as above

Building Only

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

# 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:
# On NixOS, check firewall status
sudo iptables -L

# Allow port temporarily
sudo iptables -A INPUT -p tcp --dport 3000 -j ACCEPT
  1. Verify server is listening on 0.0.0.0 (not 127.0.0.1)

Native Module Errors

If you see errors about node-pty:

# 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