From 27c49964faab64102c615b670b14bdf1fe596323 Mon Sep 17 00:00:00 2001
From: Michael Mainguy <mike.mainguy@gmail.com>
Date: Sun, 23 Nov 2025 13:03:24 -0600
Subject: [PATCH] Add Alpine Linux service setup documentation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Created comprehensive guide for running Babylon MCP server as an
OpenRC service on Alpine Linux. Includes:
- Service file configuration
- User setup (dedicated vs root)
- Service management commands
- Troubleshooting guide
- Integration with Cloudflare Tunnel
- Log rotation setup

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 ALPINE_SERVICE.md | 370 ++++++++++++++++++++++++++++++++++++++++++++++
 CLOUDFLARE.md     |   0
 2 files changed, 370 insertions(+)
 create mode 100644 ALPINE_SERVICE.md
 create mode 100644 CLOUDFLARE.md

diff --git a/ALPINE_SERVICE.md b/ALPINE_SERVICE.md
new file mode 100644
index 0000000..6056215
--- /dev/null
+++ b/ALPINE_SERVICE.md
@@ -0,0 +1,370 @@
+# Running Babylon MCP Server as an Alpine Linux Service
+
+This guide explains how to run the Babylon MCP server as a system service on Alpine Linux using OpenRC.
+
+## Prerequisites
+
+- Babylon MCP server installed and built
+- Repositories cloned and indexed
+- Application working when run manually with `npm start`
+
+## Setup Instructions
+
+### 1. Create a dedicated user (recommended)
+
+```bash
+# Create a system user for running the service
+adduser -S -D -h /var/lib/babylon-mcp -s /sbin/nologin babylon-mcp
+
+# Copy application files to service directory
+mkdir -p /var/lib/babylon-mcp
+cp -r /root/babylon-mcp/* /var/lib/babylon-mcp/
+chown -R babylon-mcp:nogroup /var/lib/babylon-mcp
+```
+
+**Or run as root (simpler but less secure):**
+
+Skip this step and use `/root/babylon-mcp` as the working directory in the service file.
+
+### 2. Create the OpenRC service file
+
+```bash
+cat > /etc/init.d/babylon-mcp << 'EOF'
+#!/sbin/openrc-run
+
+name="babylon-mcp"
+description="Babylon MCP Server"
+
+# Application directory
+directory="/root/babylon-mcp"
+
+# Command to run (using node directly for better performance)
+command="/usr/local/bin/node"
+command_args="dist/mcp/index.js"
+
+# Run in background
+command_background="yes"
+pidfile="/run/${RC_SVCNAME}.pid"
+
+# Logs
+output_log="/var/log/babylon-mcp.log"
+error_log="/var/log/babylon-mcp.err"
+
+# Environment variables (optional)
+# export NODE_ENV="production"
+# export PORT="4000"
+
+depend() {
+    need net
+    after firewall
+}
+
+start_pre() {
+    # Ensure log files exist
+    touch "$output_log" "$error_log"
+
+    # Check if built
+    if [ ! -f "$directory/dist/mcp/index.js" ]; then
+        eerror "Application not built. Run 'npm run build' first."
+        return 1
+    fi
+}
+EOF
+
+chmod +x /etc/init.d/babylon-mcp
+```
+
+**If running as dedicated user:**
+
+```bash
+cat > /etc/init.d/babylon-mcp << 'EOF'
+#!/sbin/openrc-run
+
+name="babylon-mcp"
+description="Babylon MCP Server"
+
+# Run as dedicated user
+command_user="babylon-mcp:nogroup"
+
+# Application directory
+directory="/var/lib/babylon-mcp"
+
+# Command to run
+command="/usr/local/bin/node"
+command_args="dist/mcp/index.js"
+
+# Run in background
+command_background="yes"
+pidfile="/run/${RC_SVCNAME}.pid"
+
+# Logs
+output_log="/var/log/babylon-mcp.log"
+error_log="/var/log/babylon-mcp.err"
+
+depend() {
+    need net
+    after firewall
+}
+
+start_pre() {
+    # Ensure log files exist with correct permissions
+    touch "$output_log" "$error_log"
+    chown babylon-mcp:nogroup "$output_log" "$error_log"
+
+    # Check if built
+    if [ ! -f "$directory/dist/mcp/index.js" ]; then
+        eerror "Application not built. Run 'npm run build' first."
+        return 1
+    fi
+}
+EOF
+
+chmod +x /etc/init.d/babylon-mcp
+```
+
+### 3. Enable and start the service
+
+```bash
+# Enable service to start on boot
+rc-update add babylon-mcp default
+
+# Start service now
+rc-service babylon-mcp start
+
+# Check status
+rc-service babylon-mcp status
+```
+
+### 4. Verify the service is running
+
+```bash
+# Check if service is running
+rc-service babylon-mcp status
+
+# View logs
+tail -f /var/log/babylon-mcp.log
+
+# View errors
+tail -f /var/log/babylon-mcp.err
+
+# Test the server
+curl http://localhost:4000/health
+```
+
+## Service Management Commands
+
+```bash
+# Start the service
+rc-service babylon-mcp start
+
+# Stop the service
+rc-service babylon-mcp stop
+
+# Restart the service
+rc-service babylon-mcp restart
+
+# Check status
+rc-service babylon-mcp status
+
+# View logs in real-time
+tail -f /var/log/babylon-mcp.log
+
+# View error logs
+tail -f /var/log/babylon-mcp.err
+
+# Disable service from starting on boot
+rc-update del babylon-mcp default
+
+# Enable service to start on boot
+rc-update add babylon-mcp default
+```
+
+## Troubleshooting
+
+### Service won't start
+
+1. Check the error log:
+```bash
+cat /var/log/babylon-mcp.err
+```
+
+2. Verify the application is built:
+```bash
+ls -la /root/babylon-mcp/dist/mcp/index.js
+```
+
+3. Try running manually first:
+```bash
+cd /root/babylon-mcp
+node dist/mcp/index.js
+```
+
+### Permission issues
+
+If running as dedicated user, ensure proper permissions:
+```bash
+chown -R babylon-mcp:nogroup /var/lib/babylon-mcp
+```
+
+### Port already in use
+
+Check if another service is using port 4000:
+```bash
+netstat -tlnp | grep 4000
+```
+
+### Node.js not found
+
+Verify node installation and path:
+```bash
+which node
+# Should output: /usr/local/bin/node or /usr/bin/node
+
+# Update command path in /etc/init.d/babylon-mcp if needed
+```
+
+## Environment Variables
+
+To set environment variables for the service, edit `/etc/init.d/babylon-mcp` and add before the `depend()` function:
+
+```bash
+# Set environment variables
+export NODE_ENV="production"
+export PORT="4000"
+export TRANSFORMERS_BACKEND="wasm"  # For Alpine Linux
+```
+
+## Updating the Application
+
+When you update the code:
+
+```bash
+# 1. Stop the service
+rc-service babylon-mcp stop
+
+# 2. Pull changes
+cd /root/babylon-mcp
+git pull
+
+# 3. Rebuild
+npm run build
+
+# 4. Start the service
+rc-service babylon-mcp start
+```
+
+## Running with npm start (alternative)
+
+If you prefer to use `npm start` instead of running node directly:
+
+```bash
+cat > /etc/init.d/babylon-mcp << 'EOF'
+#!/sbin/openrc-run
+
+name="babylon-mcp"
+description="Babylon MCP Server"
+directory="/root/babylon-mcp"
+command="/usr/bin/npm"
+command_args="start"
+command_background="yes"
+pidfile="/run/${RC_SVCNAME}.pid"
+output_log="/var/log/babylon-mcp.log"
+error_log="/var/log/babylon-mcp.err"
+
+depend() {
+    need net
+    after firewall
+}
+EOF
+
+chmod +x /etc/init.d/babylon-mcp
+```
+
+**Note:** Using `node` directly is more efficient and faster than using `npm start`.
+
+## Integration with Cloudflare Tunnel
+
+If you're running Cloudflare Tunnel, ensure both services start in the correct order:
+
+```bash
+# In /etc/init.d/cloudflared, add:
+depend() {
+    need net babylon-mcp
+    after firewall
+}
+```
+
+This ensures the MCP server starts before the tunnel.
+
+## Monitoring and Logs
+
+### View live logs
+```bash
+tail -f /var/log/babylon-mcp.log
+```
+
+### Rotate logs (optional)
+
+Create `/etc/logrotate.d/babylon-mcp`:
+```
+/var/log/babylon-mcp.log
+/var/log/babylon-mcp.err {
+    daily
+    missingok
+    rotate 7
+    compress
+    notifempty
+    create 0640 root root
+    sharedscripts
+    postrotate
+        rc-service babylon-mcp restart > /dev/null 2>&1 || true
+    endscript
+}
+```
+
+## Complete Setup Script
+
+For a fresh Alpine installation, run:
+
+```bash
+#!/bin/sh
+# Complete setup script
+
+# Create service file
+cat > /etc/init.d/babylon-mcp << 'EOF'
+#!/sbin/openrc-run
+name="babylon-mcp"
+description="Babylon MCP Server"
+directory="/root/babylon-mcp"
+command="/usr/local/bin/node"
+command_args="dist/mcp/index.js"
+command_background="yes"
+pidfile="/run/${RC_SVCNAME}.pid"
+output_log="/var/log/babylon-mcp.log"
+error_log="/var/log/babylon-mcp.err"
+
+depend() {
+    need net
+    after firewall
+}
+
+start_pre() {
+    touch "$output_log" "$error_log"
+    if [ ! -f "$directory/dist/mcp/index.js" ]; then
+        eerror "Application not built. Run 'npm run build' first."
+        return 1
+    fi
+}
+EOF
+
+# Make executable
+chmod +x /etc/init.d/babylon-mcp
+
+# Enable and start
+rc-update add babylon-mcp default
+rc-service babylon-mcp start
+
+echo "✓ Babylon MCP service configured and started"
+echo "Check status: rc-service babylon-mcp status"
+echo "View logs: tail -f /var/log/babylon-mcp.log"
+```
diff --git a/CLOUDFLARE.md b/CLOUDFLARE.md
new file mode 100644
index 0000000..e69de29