managarten/scripts/mac-mini/README.md

Mac Mini Server Scripts

Scripts for managing the Mana production environment on Mac Mini.

Quick Start (After System Update)

# 1. SSH into Mac Mini (from your local machine)
ssh mac-mini

# 2. Navigate to project
cd ~/projects/mana-monorepo

# 3. Setup auto-start (only needed once)
./scripts/mac-mini/setup-autostart.sh

# 4. Check status
./scripts/mac-mini/status.sh

Scripts Overview

Script	Purpose
setup-autostart.sh	Configure automatic startup on boot (run once)
startup.sh	Main startup script (called by launchd)
health-check.sh	Check all services health
status.sh	Show full system status
restart.sh	Restart all Docker containers
stop.sh	Stop all Docker containers
deploy.sh	Pull latest images and deploy

First-Time Setup

1. Prerequisites on Mac Mini

# Install Homebrew
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install required tools
brew install cloudflared git docker

# Install Docker Desktop
# Download from: https://www.docker.com/products/docker-desktop/

2. Clone Repository

mkdir -p ~/projects
cd ~/projects
git clone https://github.com/Memo-2023/mana-monorepo.git
cd mana-monorepo

3. Configure Cloudflare Tunnel

# Login to Cloudflare
cloudflared tunnel login

# The tunnel is already created (ID: bb0ea86d-8253-4a54-838b-107bb7945be9)
# Credentials should be at: ~/.cloudflared/bb0ea86d-8253-4a54-838b-107bb7945be9.json

4. Configure Environment

# Copy and edit the environment file
cp .env.macmini.example .env.macmini
nano .env.macmini

5. Enable Auto-Start

# This sets up all launchd services
./scripts/mac-mini/setup-autostart.sh

6. Configure Docker Desktop

Open Docker Desktop and enable:

• Settings > General > Start Docker Desktop when you sign in

Daily Operations

Check Status

./scripts/mac-mini/status.sh

Run Health Check

./scripts/mac-mini/health-check.sh

Restart Services

# Normal restart
./scripts/mac-mini/restart.sh

# Pull latest images and restart
./scripts/mac-mini/restart.sh --pull

# Force recreate containers
./scripts/mac-mini/restart.sh --force

View Logs

# Startup log
tail -f /tmp/mana-startup.log

# Health check log
tail -f /tmp/mana-health.log

# Cloudflare tunnel log
tail -f /tmp/cloudflared.log

# Specific container logs
docker logs -f mana-auth
docker logs -f chat-backend

Stop Services

./scripts/mac-mini/stop.sh

LaunchD Services

Three services are configured to run automatically:

Service	Label	Purpose
Cloudflared	com.cloudflare.cloudflared	Tunnel to Cloudflare
Docker Startup	com.mana.docker-startup	Start containers on boot
Health Check	com.mana.health-check	Check every 5 minutes
STT Service	com.mana.stt	Speech-to-Text (Whisper + Voxtral)

Manual Service Control

# Check status
launchctl list | grep -E 'cloudflare|mana'

# Restart a service
launchctl kickstart -k gui/$(id -u)/com.mana.docker-startup

# Stop a service
launchctl unload ~/Library/LaunchAgents/com.mana.docker-startup.plist

# Start a service
launchctl load ~/Library/LaunchAgents/com.mana.docker-startup.plist

Troubleshooting

Docker not starting

# Check if Docker Desktop is running
docker info

# Start Docker Desktop manually
open -a Docker

Cloudflare tunnel not connecting

# Check cloudflared status
pgrep -x cloudflared

# View tunnel logs
tail -50 /tmp/cloudflared.log

# Restart tunnel
launchctl kickstart -k gui/$(id -u)/com.cloudflare.cloudflared

Container health check failing

# Check specific container
docker logs <container-name>

# Restart specific container
docker restart <container-name>

# Check database connectivity
docker exec mana-postgres pg_isready -U postgres

Services not starting on boot

# Re-run setup
./scripts/mac-mini/setup-autostart.sh

# Check launchd errors
launchctl error <exit-code>

# Verify plist files
plutil ~/Library/LaunchAgents/com.mana.*.plist

Push Notifications (Optional)

To receive notifications when health checks fail:

1. Create a topic at ntfy.sh
2. Add to your shell profile:

   export NTFY_TOPIC=your-topic-name
   

3. Subscribe on your phone using the ntfy app

URLs

Once running, services are available at:

Service	URL
Unified App	https://mana.how
Auth API	https://auth.mana.how
API Gateway	https://api.mana.how
Forgejo (Git)	https://git.mana.how
Grafana	https://grafana.mana.how
Status Page	https://status.mana.how
GlitchTip	https://glitchtip.mana.how
Umami	https://stats.mana.how
SSH	ssh mac-mini (via cloudflared)

Native Services (non-Docker)

Ollama (LLM)

Ollama runs natively on Mac Mini for LLM inference:

# Check status
curl http://localhost:11434/api/tags

# List models
ollama list

# Pull a model
ollama pull gemma3:4b

AI Services (STT, TTS, LLM, Image-Gen, Video-Gen)

These have moved off the Mac Mini entirely. They run on the Windows GPU server (mana-server-gpu) as Windows Scheduled Tasks. See docs/WINDOWS_GPU_SERVER_SETUP.md for setup, and the per-service services/mana-{stt,tts,llm,image-gen,video-gen}/CLAUDE.md files for endpoint details.

Public URLs (proxied via Cloudflare Tunnel + the Mac Mini gpu-proxy):

• https://gpu-stt.mana.how
• https://gpu-tts.mana.how
• https://gpu-llm.mana.how
• https://gpu-img.mana.how
• https://gpu-video.mana.how