jknapp
1d7f18018d
Node.js/TypeScript relay server that enables remote access to MacroPad: - WebSocket-based communication between desktop and relay - Password authentication with bcrypt hashing - Session management with consistent IDs - REST API proxying to desktop app - Web client WebSocket relay - Login page and PWA-ready app page - Designed for cloud-node-container deployment 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
125 lines
2.5 KiB
Markdown
125 lines
2.5 KiB
Markdown
# MacroPad Relay Server - Deployment Guide
|
|
|
|
## Cloud Node Container Deployment
|
|
|
|
For AnHonestHost cloud-node-container deployment:
|
|
|
|
### 1. Build Locally
|
|
|
|
```bash
|
|
cd /home/jknapp/code/macropad/macropad-relay
|
|
npm install
|
|
npm run build
|
|
```
|
|
|
|
### 2. Prepare Deployment Package
|
|
|
|
The build outputs to `dist/` with public files copied. Upload:
|
|
|
|
```bash
|
|
# Upload built files to your node container app directory
|
|
rsync -avz --exclude 'node_modules' --exclude 'src' --exclude '.git' \
|
|
dist/ package.json public/ \
|
|
user@YOUR_SERVER:/path/to/app/
|
|
```
|
|
|
|
### 3. On Server
|
|
|
|
The cloud-node-container will automatically:
|
|
- Install dependencies from package.json
|
|
- Start the app using PM2
|
|
- Configure the process from package.json settings
|
|
|
|
### 4. Create Data Directory
|
|
|
|
```bash
|
|
mkdir -p /path/to/app/data
|
|
```
|
|
|
|
## Directory Structure on Server
|
|
|
|
```
|
|
app/
|
|
├── index.js # Main entry (compiled)
|
|
├── config.js
|
|
├── server.js
|
|
├── services/
|
|
├── handlers/
|
|
├── utils/
|
|
├── public/
|
|
│ ├── login.html
|
|
│ └── app.html
|
|
├── data/
|
|
│ └── sessions.json # Created automatically
|
|
└── package.json
|
|
```
|
|
|
|
## Update After Code Changes
|
|
|
|
```bash
|
|
# On local machine:
|
|
cd /home/jknapp/code/macropad/macropad-relay
|
|
npm run build
|
|
|
|
rsync -avz --exclude 'node_modules' --exclude 'src' --exclude '.git' --exclude 'data' \
|
|
dist/ package.json public/ \
|
|
user@YOUR_SERVER:/path/to/app/
|
|
|
|
# On server - restart via your container's control panel or:
|
|
pm2 restart macropad-relay
|
|
```
|
|
|
|
## Environment Variables
|
|
|
|
Set these in your container configuration:
|
|
|
|
- `PORT` - Server port (default: 3000)
|
|
- `DATA_DIR` - Data storage path (default: ./data)
|
|
- `NODE_ENV` - production or development
|
|
- `LOG_LEVEL` - info, debug, error
|
|
|
|
## Test It Works
|
|
|
|
```bash
|
|
# Test health endpoint
|
|
curl http://localhost:3000/health
|
|
|
|
# Should return:
|
|
# {"status":"ok","desktopConnections":0,"webClients":0,"sessions":[]}
|
|
```
|
|
|
|
## Nginx/Reverse Proxy (for HTTPS)
|
|
|
|
```nginx
|
|
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;
|
|
|
|
# WebSocket timeout (24 hours)
|
|
proxy_read_timeout 86400;
|
|
}
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
**Check logs:**
|
|
```bash
|
|
pm2 logs macropad-relay
|
|
```
|
|
|
|
**Check sessions:**
|
|
```bash
|
|
cat /path/to/app/data/sessions.json
|
|
```
|
|
|
|
**Port in use:**
|
|
```bash
|
|
lsof -i :3000
|
|
```
|