Files
ai-soulmate-local-deployment/skills/ai-soulmate-local-deployment/SKILL.md
T

5.9 KiB
Raw Blame History

name, description
name description
ai-soulmate-local-deployment Guide cross-computer continuation of the AI SoulMate Ubuntu private-deployment work, including SSH access, hardware baselines, Git deployment archival, Docker prerequisites, service-boundary decisions, and benchmark preparation. Use when Codex needs to resume, document, or operationalize AI SoulMate local deployment on an Ubuntu 22.04 adaptation server.

AI SoulMate Local Deployment

Use this skill to resume the AI SoulMate private-deployment adaptation without treating an unfinished POC as production-ready. Keep the deployment/orchestration repository separate from the three business-source repositories.

First actions

  1. Locate the deployment repository and read docs/CROSS-COMPUTER-HANDOFF.md, docs/IMPLEMENTATION-ROADMAP.md, docs/ARCHITECTURE.md, and inventory/source-baselines.yml when they are present.
  2. Check whether the deployment repository exists, whether it has a Git history, and whether a remote is configured. Do not assume that work from another computer is present.
  3. Inspect each source repository with git status --short and git rev-parse HEAD. Preserve unrelated working-tree changes.
  4. Record the current host facts before changing packages, network settings, storage, or container limits.

Repository boundary

  • Store Compose files, environment examples, version pins, migrations manifest, backup procedures, host-fact collectors, benchmark metadata, and reports in the deployment repository.
  • Keep Python/Vue platform code in ai-soulmate-server, farm-side code in ai-soulmate-client, and management code in mlkj-admin.
  • Record source SHAs and image digests; do not copy source trees into the deployment repository or use submodules as the release mechanism.
  • Do not add passwords, API keys, certificates, customer data, machine UUIDs, MAC addresses, or raw sensitive logs to Git.

SSH and network workflow

  • Connect to a local console first. Confirm the wired interface has a routable address with nmcli device status and ip -br addr.
  • Treat enp1s0 and eno1 as examples, not assumptions; connect only the interface with the cable and expected network profile.
  • Use a DHCP reservation or an approved static address. A private address such as 192.168.3.102 is reachable from another computer only when routing, VLAN policy, and Wi-Fi isolation permit it.
  • Install openssh-server, enable ssh, and validate with sudo sshd -t and ss -lntp.
  • Establish Ed25519 key login from the operator computer. Keep the password-login session open until a second key-based session is proven.
  • Never expose SSH, databases, Redis, or object-storage administration ports to the public Internet. Use an approved VPN for cross-site access.

Host preparation

  1. Save a sanitized host baseline: Ubuntu version, kernel, CPU, memory, swap, block layout, filesystem capacity, link state, Docker version, and time synchronization. Omit IP, MAC, serial, and UUID unless the user explicitly requests an internal inventory.
  2. Set the approved timezone and verify NTP.
  3. Apply Ubuntu security updates and install only necessary tools (git, curl, ca-certificates, gnupg, jq, rsync, tmux, monitoring and storage tools).
  4. Install Docker Engine, Buildx, and Compose plugin from Docker's official Ubuntu repository. Do not use an unreviewed curl-to-shell installer.
  5. Reboot only after recording whether a reboot is required, then recheck the reserved IP, SSH, Docker, disk space, and memory.

Deployment gates

Do not publish a runnable production Compose until these gates pass:

  • P1: platform and admin Alibaba OSS calls are behind a storage provider interface; a local S3-compatible provider passes presigned upload/download, CORS, multipart, metadata, permission, backup, and restore tests.
  • P2: mlkj-admin has an AI SoulMate-only mode that does not initialize unrelated databases; default accounts and fixed passwords are removed from delivery data.
  • P3: images are immutable and version-pinned; no source bind mounts; services have health checks, resource limits, persistent volumes, migrations, backups, restore, and controlled ports.
  • P4: core workflow works with Tripo outbound access, host reboot, and backup recovery; Tripo remains explicitly marked as an external dependency.
  • P5: farm workstation has device-specific credentials, idempotent tasks, retry/offline behavior, and printer/Moonraker validation.

The current public-domain nginx-server configuration is not a private deployment artifact. Reuse the gateway responsibility, but create environment-neutral routes for platform frontend, backend, admin, and later farm endpoints; use a customer gateway when one already exists.

Benchmark workflow

  • Separate local-only capacity from Tripo end-to-end experience. Report Tripo submit, polling, download, rate-limit, and external queue time independently.
  • Use fixed datasets and request mixes. Ramp concurrency gradually (1, 2, 5, 10, 15, 20...), warm up, hold a 15–30 minute steady period, cool down, and repeat each point at least three times.
  • Capture throughput, success/error rate, p50/p95/p99, queue depth, CPU/load, memory and swap, disk latency/utilization, network, container restarts/OOM, database pool/slow queries/locks, Redis latency/eviction, object-storage latency, and Tripo timing/errors.
  • Stop on OOM, sustained swapping, repeated restarts, data errors, growing queue, exhausted pools, or sustained SLA/error/latency failure. Do not turn one failed point into a customer concurrency promise.
  • Archive sanitized metadata and summary reports; keep large raw logs outside Git unless explicitly approved.

Handoff output

At the end of each session, update the handoff document with completed commands, exact versions, unresolved blockers, and the next safe action. If the deployment repository is new, show its Git status and whether the first commit and remote push were completed; never claim archival until a commit exists.