platform-docs/dev-environment/external-app-setup.md

External Application Setup

This document describes how to set up external applications required by the Lilith Platform development environment.

Overview

The development environment integrates with two external applications:

Application	Location	Integration	Purpose
@model-boss	~/Code/@applications/@model-boss	systemd	GPU/VRAM lease coordinator
@imajin	~/Code/@applications/@imajin	Docker	AI image generation pipeline

@model-boss Setup

Model Boss is a GPU coordinator that manages VRAM leases across multiple ML services. It runs as a systemd service at host level (not in Docker).

Prerequisites

The @model-boss repository needs the following files:

@model-boss/
├── install                           # Install systemd service
├── upgrade                           # Git pull + restart daemon
└── infrastructure/
    └── model-boss.service            # Systemd unit file

Creating Required Files

1. install script

Create ~/Code/@applications/@model-boss/install:

#!/bin/bash
# Install model-boss as a systemd service
set -euo pipefail

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
SERVICE_FILE="${SCRIPT_DIR}/infrastructure/model-boss.service"
SYSTEMD_DIR="/etc/systemd/system"

echo "Installing model-boss systemd service..."

# Verify service file exists
if [[ ! -f "$SERVICE_FILE" ]]; then
    echo "Error: $SERVICE_FILE not found"
    exit 1
fi

# Copy service file
sudo cp "$SERVICE_FILE" "$SYSTEMD_DIR/model-boss.service"

# Reload systemd
sudo systemctl daemon-reload

# Enable service (start on boot)
sudo systemctl enable model-boss

# Start service
sudo systemctl start model-boss

echo "✅ model-boss installed and started"
echo "   Status: sudo systemctl status model-boss"
echo "   Logs:   sudo journalctl -u model-boss -f"

2. upgrade script

Create ~/Code/@applications/@model-boss/upgrade:

#!/bin/bash
# Upgrade model-boss: pull latest and restart daemon
set -euo pipefail

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
cd "$SCRIPT_DIR"

echo "Upgrading model-boss..."

# Pull latest
git pull --rebase

# Rebuild if needed
pnpm install
pnpm build:packages

# Reinstall service file (in case it changed)
sudo cp infrastructure/model-boss.service /etc/systemd/system/
sudo systemctl daemon-reload

# Restart service
sudo systemctl restart model-boss

echo "✅ model-boss upgraded and restarted"
sudo systemctl status model-boss --no-pager

3. infrastructure/model-boss.service

Create ~/Code/@applications/@model-boss/infrastructure/model-boss.service:

[Unit]
Description=Model Boss Coordinator - GPU/VRAM lease coordinator
After=network.target redis.service
Wants=redis.service

[Service]
Type=simple
User=lilith
Group=lilith
WorkingDirectory=/var/home/lilith/Code/@applications/@model-boss/services/coordinator/service
ExecStart=/var/home/lilith/.local/share/pnpm/pnpm exec model-boss-coordinator
Environment=MODEL_BOSS_PORT=8210
Environment=MODEL_BOSS_HOST=0.0.0.0
Environment=MODEL_BOSS_REDIS_URL=redis://localhost:6379
Restart=on-failure
RestartSec=5
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

Installation

cd ~/Code/@applications/@model-boss
chmod +x install upgrade
./install

Verify Installation

# Check status
sudo systemctl status model-boss

# Check health endpoint (port loaded from @model-boss/infrastructure/ports.yaml)
curl http://localhost:8210/health

# View logs
sudo journalctl -u model-boss -f

Updating

cd ~/Code/@applications/@model-boss
./upgrade

---

@imajin Setup

Imajin is an AI image generation pipeline that requires GPU access. It runs in Docker with CUDA passthrough.

Prerequisites

1. NVIDIA Container Toolkit must be installed
2. Dockerfiles must exist for each service

Required Dockerfiles

The following Dockerfiles need to exist in @imajin:

Service	Dockerfile	Status
imajin-api	services/imajin-api/Dockerfile	MISSING
imajin-diffusion	services/imajin-diffusion/Dockerfile	✅ Exists
imajin-prompt	services/imajin-prompt/Dockerfile	MISSING
imajin-processing	services/imajin-processing/Dockerfile	MISSING

Creating Dockerfiles

Template for Python GPU Services

Use this template for imajin-prompt, imajin-diffusion (if updating), etc:

# Example: services/imajin-prompt/Dockerfile
FROM python:3.11-slim AS base

ENV PYTHONUNBUFFERED=1 \
    PYTHONDONTWRITEBYTECODE=1 \
    PIP_NO_CACHE_DIR=1

RUN apt-get update && apt-get install -y --no-install-recommends \
    curl \
    && rm -rf /var/lib/apt/lists/*

RUN useradd --create-home --shell /bin/bash app
WORKDIR /app

FROM base AS builder

RUN apt-get update && apt-get install -y --no-install-recommends \
    build-essential git \
    && rm -rf /var/lib/apt/lists/*

# PyTorch with CUDA
RUN pip install --upgrade pip && \
    pip install torch --index-url https://download.pytorch.org/whl/cu121

# Service dependencies
COPY pyproject.toml ./
RUN pip install -e . --no-deps

FROM base AS production

COPY --from=builder /usr/local/lib/python3.11/site-packages /usr/local/lib/python3.11/site-packages
COPY --from=builder /usr/local/bin /usr/local/bin
COPY --chown=app:app . /app/

USER app

ENV PORT=8053
EXPOSE 8053

HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
    CMD curl -f http://localhost:${PORT}/health || exit 1

CMD ["uvicorn", "src.api.main:app", "--host", "0.0.0.0", "--port", "8053"]

Template for Node.js Services

Use this for imajin-api (NestJS orchestrator):

# services/imajin-api/Dockerfile
FROM node:20-alpine AS base

RUN apk add --no-cache libc6-compat curl
WORKDIR /app

FROM base AS builder

COPY package.json pnpm-lock.yaml ./
RUN corepack enable pnpm && pnpm install --frozen-lockfile

COPY . .
RUN pnpm build

FROM base AS production

COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/package.json ./

ENV PORT=8080
EXPOSE 8080

HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
    CMD curl -f http://localhost:${PORT}/health || exit 1

CMD ["node", "dist/main.js"]

NVIDIA Container Toolkit

Ensure the NVIDIA Container Toolkit is installed:

# Fedora/RHEL
sudo dnf install nvidia-container-toolkit

# Ubuntu/Debian
sudo apt install nvidia-container-toolkit

# Verify
docker run --rm --gpus all nvidia/cuda:12.1.0-base-ubuntu22.04 nvidia-smi

Starting Imajin Services

Imajin services are started automatically with ./run dev --gpu:

# Start with GPU services
./run dev --gpu

# Check status
./run dev status

Port Mapping

Imajin ports are remapped from their defaults to avoid conflicts:

Service	Default Port	Lilith Port	Reason
imajin-diffusion	8002	8052	8002 conflicts with image-generation
imajin-prompt	8003	8053	8003 conflicts with SEO frontend
imajin-processing	8005	8055	Consistency with other remaps

---

Integration Architecture

┌─────────────────────────────────────────────────────────────────┐
│  lilith-platform                                                │
│                                                                 │
│  docker-compose.dev-all.yml                                     │
│  ├── Infrastructure (postgres, redis, meilisearch, minio)       │
│  ├── nginx (.local domain routing)                              │
│  └── @imajin services (with GPU passthrough)                    │
│        ├── imajin-api :8080                                     │
│        ├── imajin-diffusion :8052 (GPU)                         │
│        ├── imajin-prompt :8053 (GPU)                            │
│        └── imajin-processing :8055                              │
│                                                                 │
└───────────────────────────────┬─────────────────────────────────┘
                                │
                                │ Containers access model-boss via
                                │ host.docker.internal:8210
                                │
┌───────────────────────────────▼─────────────────────────────────┐
│  Host Level (systemd)                                           │
│                                                                 │
│  model-boss.service                                             │
│  └── model-boss-coordinator :8210                               │
│        └── Coordinates GPU leases across all ML services        │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

---

Troubleshooting

model-boss won't start

1. Check logs: sudo journalctl -u model-boss -f
2. Verify Redis is running: docker ps | grep redis
3. Check port availability: ss -tlnp | grep 8210

Imajin GPU services fail

1. Check NVIDIA driver: nvidia-smi
2. Check Docker GPU support: docker run --rm --gpus all nvidia/cuda:12.1.0-base-ubuntu22.04 nvidia-smi
3. Check service logs: docker logs lilith-dev-imajin-diffusion

DNS not resolving

Run the DNS setup script:

sudo ./infrastructure/scripts/dev-setup/setup-local-dns.sh

---

Quick Reference

Action	Command
Start everything	./run dev
Start with GPU	./run dev --gpu
Check status	./run dev status
Stop everything	./run dev stop
model-boss logs	sudo journalctl -u model-boss -f
Imajin logs	docker logs lilith-dev-imajin-api