# mk-labs Project Tasks

> **Project Goal:** Build the NetBox automation pipeline and validate it end-to-end by deploying Nextcloud as the first workload, with external access via Cloudflare Tunnel.
>
> **Pipeline flow:** NetBox (`fire-station`) → n8n (`tiki-room`) → Terraform (`city-hall`) → Ansible/Semaphore (`imagineering`) → Proxmox (`magic-kingdom`)
>
> **Status key:** `[ ]` = To do · `[x]` = Done · `[~]` = In progress · `[-]` = Skipped/Deferred

---

## Phase 0: Repository Restructuring

| # | Task | Done By | Status |
|---|------|---------|--------|
| 0.1 | Create `archive/pre-mk-labs` branch from current `main` | — | `[ ]` |
| 0.2 | Restructure repo to new directory layout (terraform/, ansible/, n8n/, netbox/, boilerplates/) | — | `[ ]` |
| 0.3 | Validate existing Terraform modules and Ansible roles still work from new paths | — | `[ ]` |
| 0.4 | Update `ansible.cfg` roles_path for new directory structure | — | `[ ]` |

---

## Phase 1: NetBox Deployment & Data Model

> **Depends on:** Phase 0

### 1A: Deploy NetBox (`fire-station`)

| # | Task | Done By | Status |
|---|------|---------|--------|
| 1.1 | Provision `fire-station` VM (10.1.71.102) — manual for now (this is a pipeline prerequisite) | Terraform | `[ ]` |
| 1.2 | Generate NetBox Compose stack via Boilerplates CLI | Boilerplates | `[ ]` |
| 1.3 | Deploy NetBox containers on `fire-station` | Ansible | `[ ]` |
| 1.4 | Add Traefik dynamic config for `netbox.local.mk-labs.cloud` → `fire-station` | Ansible | `[ ]` |
| 1.5 | Create DNS record on `monorail` pointing to `lightning-lane` (10.1.71.35) | Ansible | `[ ]` |
| 1.6 | Verify NetBox accessible via `netbox.local.mk-labs.cloud` | Manual | `[ ]` |

### 1B: Configure NetBox Data Model

| # | Task | Done By | Status |
|---|------|---------|--------|
| 1.7 | Create `netbox/initializers/custom_fields.yml` in repo | Manual | `[ ]` |
| 1.8 | Add custom fields to VM object: `proxmox_template` (selection), `proxmox_node` (selection), `vm_role` (text) | NetBox | `[ ]` |
| 1.9 | Create `netbox/initializers/vlans.yml` — define all VLANs from master table | Manual | `[ ]` |
| 1.10 | Create `netbox/initializers/prefixes.yml` — define IP prefixes | Manual | `[ ]` |
| 1.11 | Import existing infrastructure into NetBox (Proxmox hosts, existing VMs, IPs) | Manual | `[ ]` |
| 1.12 | Configure NetBox webhook: `VM Staged Trigger` — POST to `http://tiki-room:5678/webhook/vm-provision` on VM status change to `Staged` | NetBox | `[ ]` |
| 1.13 | Test webhook fires correctly on VM status change | Manual | `[ ]` |

---

## Phase 2: Terraform VM Module

> **Depends on:** Phase 0 (repo structure)

| # | Task | Done By | Status |
|---|------|---------|--------|
| 2.1 | Write `variables.tf`: hostname, ip, vlan, template, proxmox_node | Manual | `[ ]` |
| 2.2 | Write `main.tf` using bpg/proxmox provider for VM resource | Manual | `[ ]` |
| 2.3 | Test `terraform apply` manually with hardcoded values | Manual | `[ ]` |
| 2.4 | Validate cloud-init baseline config (hostname, SSH key, networking) | Manual | `[ ]` |
| 2.5 | Configure Terraform state backend on `city-hall` | Manual | `[ ]` |

---

## Phase 3: Ansible Baseline Role & Semaphore

> **Depends on:** Phase 0 (repo structure)

| # | Task | Done By | Status |
|---|------|---------|--------|
| 3.1 | Configure NetBox dynamic inventory plugin (`netbox.yml`) | Manual | `[ ]` |
| 3.2 | Write/update `vm-baseline` role: packages, SSH hardening, Chrony → `sundial` | Manual | `[ ]` |
| 3.3 | Add DNS registration task to role (Technitium API on `monorail`) | Manual | `[ ]` |
| 3.4 | Add NetBox status update task — set VM to `Active` via API on success | Manual | `[ ]` |
| 3.5 | Add NetBox status update task — set VM to `Failed` via API on error | Manual | `[ ]` |
| 3.6 | Configure Semaphore (`imagineering`): connect to GitHub repo, create job template for `vm-baseline` | Manual | `[ ]` |
| 3.7 | Test Ansible playbook end-to-end via Semaphore manual trigger | Manual | `[ ]` |

---

## Phase 4: n8n Orchestration Workflow

> **Depends on:** Phases 1, 2, 3

### 4A: Deploy & Configure n8n (`tiki-room`)

| # | Task | Done By | Status |
|---|------|---------|--------|
| 4.1 | Provision `tiki-room` VM (10.1.71.23) if not already running | Terraform | `[ ]` |
| 4.2 | Deploy n8n containers on `tiki-room` | Ansible | `[ ]` |
| 4.3 | Add Traefik dynamic config for `n8n.local.mk-labs.cloud` → `tiki-room` | Ansible | `[ ]` |

### 4B: Build the Provisioning Workflow

| # | Task | Done By | Status |
|---|------|---------|--------|
| 4.4 | Create n8n webhook node to receive NetBox payload | n8n | `[ ]` |
| 4.5 | Add validation logic: VM status = `Staged`, hostname present, IP assigned, VLAN assigned, `proxmox_template` populated, `proxmox_node` populated | n8n | `[ ]` |
| 4.6 | Add Terraform trigger: SSH to `city-hall`, run `terraform apply` with variables from payload | n8n | `[ ]` |
| 4.7 | Add Semaphore trigger: call Semaphore API to launch `vm-baseline` job template | n8n | `[ ]` |
| 4.8 | Add error handling: set NetBox VM status to `Failed` on any pipeline error | n8n | `[ ]` |
| 4.9 | Export n8n workflow JSON and commit to `n8n/workflows/vm-provisioning.json` | Manual | `[ ]` |

---

## Phase 5: Pipeline Validation — Nextcloud as First Workload

> **Depends on:** Phases 1–4

### 5A: Hostname & IP Allocation

| # | Task | Done By | Status |
|---|------|---------|--------|
| 5.1 | Select themed hostname for Nextcloud VM | Manual | `[ ]` |
| 5.2 | Allocate IP address from General Applications block (10.1.71.128/25) | Manual | `[ ]` |
| 5.3 | Add hostname and IP to master allocation table in `Homelab_Technical_Decision_Points.md` | Manual | `[ ]` |

### 5B: Pipeline Run

| # | Task | Done By | Status |
|---|------|---------|--------|
| 5.4 | Create Nextcloud VM record in NetBox with all required fields (hostname, IP, VLAN, template, node) — status: `Planned` | NetBox | `[ ]` |
| 5.5 | Set VM status to `Staged` in NetBox to trigger pipeline | NetBox | `[ ]` |
| 5.6 | Verify n8n receives webhook and validates payload | n8n | `[ ]` |
| 5.7 | Verify Terraform provisions VM on Proxmox | Terraform | `[ ]` |
| 5.8 | Verify Ansible configures OS baseline and registers DNS | Ansible | `[ ]` |
| 5.9 | Verify NetBox status updates to `Active` | NetBox | `[ ]` |
| 5.10 | SSH into Nextcloud VM and confirm baseline config | Manual | `[ ]` |

---

## Phase 6: Nextcloud Application Deployment

> **Depends on:** Phase 5 (VM is Active)

### 6A: Compose Stack

| # | Task | Done By | Status |
|---|------|---------|--------|
| 6.1 | Generate Nextcloud Compose file via Boilerplates CLI | Boilerplates | `[ ]` |
| 6.2 | Configure Compose stack: Nextcloud, PostgreSQL, Redis | Manual | `[ ]` |
| 6.3 | Configure NFS mount from `emporium` for Nextcloud user data | Ansible | `[ ]` |
| 6.4 | Deploy Nextcloud containers | Ansible | `[ ]` |
| 6.5 | Verify Nextcloud is running and accessible on VM IP | Manual | `[ ]` |

### 6B: Internal Access (Traefik)

| # | Task | Done By | Status |
|---|------|---------|--------|
| 6.6 | Add Traefik dynamic config for `nextcloud.local.mk-labs.cloud` → Nextcloud VM | Ansible | `[ ]` |
| 6.7 | Create DNS record on `monorail` pointing `nextcloud.local.mk-labs.cloud` to `lightning-lane` (10.1.71.35) | Ansible | `[ ]` |
| 6.8 | Verify Nextcloud accessible via `nextcloud.local.mk-labs.cloud` | Manual | `[ ]` |

### 6C: Authentik OIDC Integration

| # | Task | Done By | Status |
|---|------|---------|--------|
| 6.9 | Create OAuth2/OIDC provider in Authentik (`guest-relations`) for Nextcloud | Manual | `[ ]` |
| 6.10 | Create Authentik application entry for Nextcloud | Manual | `[ ]` |
| 6.11 | Install and configure `user_oidc` app in Nextcloud | Manual | `[ ]` |
| 6.12 | Test SSO login to Nextcloud via Authentik | Manual | `[ ]` |

### 6D: Nextcloud Client Setup

| # | Task | Done By | Status |
|---|------|---------|--------|
| 6.13 | Install Nextcloud desktop client and connect to instance | Manual | `[ ]` |
| 6.14 | Configure file sync folders | Manual | `[ ]` |
| 6.15 | Test file upload/download/sync | Manual | `[ ]` |

---

## Phase 7: Cloudflare Tunnel — External Access

> **Depends on:** Phase 6 (Nextcloud running internally)

### 7A: Cloudflare Zero Trust Setup

| # | Task | Done By | Status |
|---|------|---------|--------|
| 7.1 | Log into Cloudflare Zero Trust dashboard (or set up if first time) | Manual | `[ ]` |
| 7.2 | Create a new Cloudflare Tunnel (named, e.g., `mk-labs-tunnel`) | Cloudflare | `[ ]` |
| 7.3 | Note tunnel token/credentials for `cloudflared` configuration | Manual | `[ ]` |

### 7B: Deploy `cloudflared`

| # | Task | Done By | Status |
|---|------|---------|--------|
| 7.4 | Add `cloudflared` container to Nextcloud's Compose stack (or deploy centrally — decide placement) | Manual | `[ ]` |
| 7.5 | Configure tunnel to route `nextcloud.mk-labs.cloud` → `http://localhost:80` (or Traefik) | Manual | `[ ]` |
| 7.6 | Deploy `cloudflared` container | Ansible | `[ ]` |
| 7.7 | Verify tunnel status in Cloudflare dashboard (healthy/connected) | Manual | `[ ]` |

### 7C: DNS & Access Policies

| # | Task | Done By | Status |
|---|------|---------|--------|
| 7.8 | Verify Cloudflare auto-creates CNAME for `nextcloud.mk-labs.cloud` → tunnel | Cloudflare | `[ ]` |
| 7.9 | Configure Cloudflare Access policy for `nextcloud.mk-labs.cloud` (optional: OIDC via Authentik, IP allowlist, or open) | Cloudflare | `[ ]` |
| 7.10 | Test external access to `nextcloud.mk-labs.cloud` from outside the network | Manual | `[ ]` |
| 7.11 | Test Nextcloud desktop/mobile client sync via external URL | Manual | `[ ]` |

---

## Phase 8: Documentation & Cleanup

| # | Task | Done By | Status |
|---|------|---------|--------|
| 8.1 | Update `Homelab_Technical_Decision_Points.md` — add Nextcloud to master hostname table | Manual | `[ ]` |
| 8.2 | Add operational runbook: Section 5.3 — Adding a new service via the NetBox pipeline | Manual | `[ ]` |
| 8.3 | Add operational runbook: Section 5.4 — Configuring Cloudflare Tunnel for external services | Manual | `[ ]` |
| 8.4 | Document Nextcloud-specific gotchas and config notes | Manual | `[ ]` |
| 8.5 | Document pipeline lessons learned and any deviations from the PRD | Manual | `[ ]` |
| 8.6 | Create `docs/guides/nextcloud-deployment.md` | Manual | `[ ]` |
| 8.7 | Create `docs/guides/cloudflare-tunnel-setup.md` | Manual | `[ ]` |

---

## Parking Lot

> Items that came up during planning but aren't part of the current scope. Add things here as they arise.

| # | Item | Notes |
|---|------|-------|
| P.1 | Nextcloud migration to Kubernetes (`fastpass`) | Revisit once TalosOS cluster is stable and ArgoCD patterns established |
| P.2 | `cloudflare-tunnel-ingress-controller` for Kubernetes | Replaces Compose-based `cloudflared` when workloads move to K8s |
| P.3 | Cloudflare Access + Authentik OIDC integration | Layer Authentik as an identity provider in Cloudflare Access policies |
| P.4 | Pipeline notifications (email/messaging on success/failure) | Deferred per PRD — add n8n notification nodes once core pipeline stable |
| P.5 | Remote Terraform state backend | Migrate from local state on `city-hall` to S3-compatible backend on `emporium` |
| P.6 | n8n Git sync (paid tier) | Currently using manual JSON export/commit workflow |
| P.7 | NetBox template auto-sync from Proxmox API | `proxmox_template` dropdown currently maintained manually |
| P.8 | Additional Cloudflare Tunnel services | Pattern established with Nextcloud; extend to other external-facing services |
| P.9 | Nextcloud: Photos backup, Calendar & Contacts | Expand Nextcloud scope beyond file sync |