---
name: homelab-docker-deploy
description: Scaffolds and deploys a new Docker service on TrueNAS.local homelab server. Use this skill when adding a new containerized service to the homelab — produces a docker-compose.yml, documents the service in BigMind, and verifies it is running.
---

# Homelab Docker Deploy

## When to use
- Adding a new Docker service to TrueNAS.local
- Migrating an existing service to Docker Compose format
- Recovering a stopped/broken service

## When NOT to use
- Services that should live on the Fedora workstation (not TrueNAS)
- ADP/Paisy or MCP server work

## Inputs required
- **Service name** — e.g., `gitea`, `ollama`, `homelab-monitor`
- **Image** — Docker Hub image and tag
- **Port mapping** — host:container
- **Volume paths** — TrueNAS dataset paths (e.g., `/mnt/tank/docker/gitea`)
- **Environment variables** — any required config

## Workflow

### Step 1 — Check for existing service
```bash
ssh root@192.168.188.119 "docker ps -a | grep {service-name}"
```

### Step 2 — Create dataset (if new persistent storage needed)
TrueNAS datasets live under `/mnt/tank/docker/{service-name}/`

### Step 3 — Write `docker-compose.yml`
```yaml
version: "3.8"
services:
  {service-name}:
    image: {image}:{tag}
    container_name: {service-name}
    restart: unless-stopped
    ports:
      - "{host-port}:{container-port}"
    volumes:
      - /mnt/tank/docker/{service-name}/data:/data
    environment:
      - KEY=value
```

### Step 4 — Deploy
```bash
ssh root@192.168.188.119 "cd /opt/docker/{service-name} && docker compose up -d"
```

### Step 5 — Verify
```bash
ssh root@192.168.188.119 "docker ps | grep {service-name}"
ssh root@192.168.188.119 "docker logs {service-name} --tail 20"
```

### Step 6 — Store in BigMind
```
memory_store_fact("environment-config", "Service {service-name} running on TrueNAS at port {port}. Image: {image}. Data: /mnt/tank/docker/{service-name}/")
```

### Step 7 — Commit compose file to Gitea
Use the `gitea-push` skill with type `chore` and scope `homelab`.

## Troubleshooting
- **Port conflict:** `ssh root@192.168.188.119 "ss -tlnp | grep {port}"`
- **Permission denied on /mnt:** Check ZFS dataset ownership
- **Image pull fails:** TrueNAS needs outbound internet — check DNS and routing