How I Deploy Apps to My Homelab (A Love Story in 9 Acts)

new_repo my-brilliant-idea

// Go: when you want to feel productive
func main() {
    port := getEnvInt("PORT", 7234)
    http.HandleFunc("/health", healthCheck)
    http.ListenAndServe(fmt.Sprintf(":%d", port), nil)
}

# Python: when you want to feel happy
app = Flask(__name__)

@app.route('/health')
def health():
    return {'status': 'ok', 'mood': 'cautiously optimistic'}

- name: Git checkout my-brilliant-idea
  ansible.builtin.git:
    repo: "{{ git_base_url }}/my-brilliant-idea"
    dest: "{{ base_folder }}/my-brilliant-idea"
  register: update_git

- name: Build it
  shell: "go build -o my-brilliant-idea ."
  when: update_git.changed

- name: Systemd service
  become: yes
  copy:
    content: |
      [Unit]
      Description=My Brilliant Idea
      [Service]
      ExecStart={{ base_folder }}/my-brilliant-idea/my-brilliant-idea
      Environment="PORT=7234"
      Restart=always
    dest: /etc/systemd/system/my-brilliant-idea.service

my_brilliant_idea:
  services:
    my_brilliant_idea:
      port: 7234
      domain: "brilliant.lan"
      display_name: "My Brilliant Idea"
      description: "Does something brilliant, probably"
      icon: "💡"

# Regenerate cert with all domains
lan-ca generate $(cat host_records.json | jq -r '.[].aliasName' | tr '\n' ' ')

# Copy to Caddy role and deploy
cp ~/.lan-ca/certs/* ~/repos/homelab/roles/caddy/files/certs/
ansible-playbook playbook_main.yml --tags caddy

cd ~/repos/homelab
source bin/activate

# Deploy the service
ansible-playbook playbook_services_experimental.yml --tags my-brilliant-idea

# Deploy Caddy (reverse proxy)
ansible-playbook playbook_main.yml --tags caddy --limit robot.lan

# Deploy DNS
ansible-playbook playbook_main.yml --tags unifi_dns

# Deploy monitoring
ansible-playbook playbook_main.yml --tags gatus

# Homelab Deployment Guide

Guide for deploying Go and Python services to robot.lan via Ansible.

## Overview

Services are deployed to `robot.lan` (experimental host) using Ansible roles in `~/repos/homelab`.

## Port Selection

Pick a random port between 4000-9999 to avoid collisions. Already used ports:
- 4444: nvr-proxy (NVR frame caching)
- 5555: leonie_sleeps (sleep tracking)
- 8080: (commonly used, avoid)
- 8888: (commonly used, avoid)

## Creating a New Service

### Step 1: Create the Repository

Use the `new_repo` command to create a new git repo:
new_repo my-service

### Step 2: Write the Service

#### Go Service Template
package main

import (
    "fmt"
    "log"
    "net/http"
    "os"
    "strconv"
)

func getEnvInt(key string, fallback int) int {
    if v := os.Getenv(key); v != "" {
        if i, err := strconv.Atoi(v); err == nil {
            return i
        }
    }
    return fallback
}

func main() {
    port := getEnvInt("PORT", 7234)  // Pick random port!

    http.HandleFunc("/health", func(w http.ResponseWriter, r *http.Request) {
        w.Write([]byte(`{"status":"ok"}`))
    })

    log.Printf("Starting on port %d", port)
    http.ListenAndServe(fmt.Sprintf(":%d", port), nil)
}

#### Python Service Template (Flask)
from flask import Flask
import os

app = Flask(__name__)

@app.route('/health')
def health():
    return {'status': 'ok'}

if __name__ == '__main__':
    port = int(os.environ.get('PORT', 7234))
    app.run(host='0.0.0.0', port=port)

### Step 3: Create Ansible Role

Create `~/repos/homelab/roles/<service_name>/tasks/main.yml`

### Step 4: Add to Playbook

Edit `~/repos/homelab/playbook_services_experimental.yml`

### Step 5: Deploy

cd ~/repos/homelab
source bin/activate
ansible-playbook playbook_services_experimental.yml --tags <service>

## CRITICAL: Deploy Caddy to the Target Host

When deploying a new service, DNS creates a CNAME that points the service
domain to the target host. Caddy must be deployed on that same host.

### Correct Deployment Sequence
1. Deploy the service
2. Deploy Caddy on the same host
3. Deploy service_index
4. Deploy DNS

## CRITICAL: Regenerate TLS Certificate for New Domains

The homelab uses explicit SANs (not wildcards). When adding a new service,
regenerate the certificate to include the new domain.