Files

jknapp 1d7f18018d Add relay server for remote HTTPS access

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>

2026-01-05 19:46:33 -08:00

2.5 KiB

Raw Blame History

MacroPad Relay Server - Deployment Guide

Cloud Node Container Deployment

For AnHonestHost cloud-node-container deployment:

1. Build Locally

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:

# 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

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

# 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

# Test health endpoint
curl http://localhost:3000/health

# Should return:
# {"status":"ok","desktopConnections":0,"webClients":0,"sessions":[]}

Nginx/Reverse Proxy (for HTTPS)

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:

pm2 logs macropad-relay

Check sessions:

cat /path/to/app/data/sessions.json

Port in use:

lsof -i :3000

2.5 KiB Raw Blame History