Amp-Thread-ID: https://ampcode.com/threads/T-a6cf4bd2-36d0-4ef8-ada6-a8e2850fcacf Co-authored-by: Amp <amp@ampcode.com>
182 lines
4 KiB
Markdown
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
|