eblume/blumeops
1
1
Fork 0
Code Issues Pull requests Projects Releases 83 Packages Wiki Activity Actions

Trim operational content from reference cards

Browse source 
Reference docs should describe "what things are", not "how to do things".
Removed:
- CLI command examples
- Operational workflows (PR workflow, sync commands)
- Setup/bootstrap procedures
- "Useful Commands" sections

Also split hosts.md into individual cards:
- infrastructure/indri.md - Primary server details
- infrastructure/gilbert.md - Development workstation

This content belongs in how-to guides (future phase).

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Erich Blume 2026-02-03 13:44:26 -08:00
commit ad7e9af453
17 changed files with 113 additions and 281 deletions
Download patch file Download diff file Expand all files Collapse all files

6
docs/reference/index.md
View file

@ -10,7 +10,7 @@ Technical specifications, inventories, and configuration details for BlumeOps in
## Services
Individual service reference cards with URLs, configuration, and operational details.
Individual service reference cards with URLs and configuration details.
| Service | Description | Location |
|---------|-------------|----------|
@ -35,7 +35,9 @@ Individual service reference cards with URLs, configuration, and operational det
Host inventory and network configuration.
- [[infrastructure/hosts|Hosts]] - Device inventory (indri, gilbert, sifaka, etc.)
- [[infrastructure/hosts|Hosts]] - Device inventory
- [[infrastructure/indri|Indri]] - Primary server
- [[infrastructure/gilbert|Gilbert]] - Development workstation
- [[infrastructure/tailscale|Tailscale]] - ACLs, groups, tags
- [[infrastructure/routing|Routing]] - DNS domains, port mappings

27
docs/reference/infrastructure/gilbert.md Normal file
View file

@ -0,0 +1,27 @@
---
title: Gilbert
tags:
- infrastructure
- host
---
# Gilbert
Primary development workstation.
## Specifications
| Property | Value |
|----------|-------|
| **Model** | 13" MacBook Air M4, 2025 |
| **User** | eblume |
| **Role** | Development workstation |
## Development Tools
Managed via `Brewfile` and `mise.toml` in the blumeops repo.
## Related
- [[infrastructure/indri|Indri]] - Server accessed from gilbert
- [[kubernetes/cluster|Cluster]] - Remote k8s access

64
docs/reference/infrastructure/hosts.md
View file

@ -10,62 +10,16 @@ All devices connected via [Tailscale](https://login.tailscale.com/) tailnet `tai
## Devices
| Host | Description | Notes |
|------|-------------|-------|
| **Indri** | Mac Mini M1, 2020 | Primary server, 2TB internal disk |
| **[[storage/sifaka|Sifaka]]** | Synology NAS | 10.9TB RAID 5, backup target |
| **Gilbert** | 13" MacBook Air M4, 2025 | Primary workstation |
| **Mouse** | 13" MacBook Air M2 | Allison's laptop |
| **UniFi** | UniFi Express 7 | Home WiFi network |
| **Dwarf** | iPad Air | Employer-provided, off tailnet |
## Indri Details
| Property | Value |
|----------|-------|
| **Model** | Mac mini M1, 2020 (Macmini9,1) |
| **Storage** | 2TB internal SSD |
| **macOS** | 15.7.3 (Sequoia) |
| **Role** | Primary server |
| **Tailscale IP** | 100.98.163.89 |
### Services Hosted
**Native (via Ansible):**
- [[services/forgejo|Forgejo]] - Git forge
- [[services/zot|Zot]] - Container registry
- [[services/jellyfin|Jellyfin]] - Media server
- [[services/borgmatic|Borgmatic]] - Backup system
- [[services/alloy|Alloy]] - Metrics/logs collector
- Caddy - Reverse proxy
**Kubernetes (via minikube):**
- [[kubernetes/apps|All k8s applications]]
### Sleep Prevention
Indri uses Amphetamine (App Store) to prevent sleep. Configuration:
- Start Session At Launch: enabled
- Default Duration: indefinite
- Allow Closed-Display Sleep: enabled
## Gilbert Details
| Property | Value |
|----------|-------|
| **Model** | 13" MacBook Air M4, 2025 |
| **Role** | Development workstation |
| **User** | eblume |
### Development Tools
Managed via `Brewfile` and `mise.toml`.
Fish abbreviations:
- `ki` -> `kubectl --context=minikube-indri`
- `k9i` -> `k9s --context=minikube-indri`
| Host | Description | Card |
|------|-------------|------|
| **Indri** | Mac Mini M1, 2020 - Primary server | [[infrastructure/indri|Details]] |
| **Gilbert** | MacBook Air M4, 2025 - Workstation | [[infrastructure/gilbert|Details]] |
| **[[storage/sifaka|Sifaka]]** | Synology NAS - Storage & backups | [[storage/sifaka|Details]] |
| **Mouse** | MacBook Air M2 - Allison's laptop | - |
| **UniFi** | UniFi Express 7 - Home WiFi | - |
| **Dwarf** | iPad Air - Employer-provided, off tailnet | - |
## Related
- [[infrastructure/tailscale|Tailscale]] - Network configuration
- [[storage/sifaka|Sifaka]] - NAS details
- [[infrastructure/routing|Routing]] - Service URLs

38
docs/reference/infrastructure/indri.md Normal file
View file

@ -0,0 +1,38 @@
---
title: Indri
tags:
- infrastructure
- host
---
# Indri
Primary BlumeOps server. Mac Mini M1 (2020).
## Specifications
| Property | Value |
|----------|-------|
| **Model** | Mac mini M1, 2020 (Macmini9,1) |
| **Storage** | 2TB internal SSD |
| **macOS** | 15.7.3 (Sequoia) |
| **Tailscale IP** | 100.98.163.89 |
| **Tailscale Tag** | `tag:homelab` |
## Services Hosted
**Native (via Ansible):**
- [[services/forgejo|Forgejo]] - Git forge
- [[services/zot|Zot]] - Container registry
- [[services/jellyfin|Jellyfin]] - Media server
- [[services/borgmatic|Borgmatic]] - Backup system
- [[services/alloy|Alloy]] - Metrics/logs collector
- Caddy - Reverse proxy for `*.ops.eblu.me`
**Kubernetes (via minikube):**
- [[kubernetes/apps|All k8s applications]]
## Related
- [[infrastructure/routing|Routing]] - Port mappings
- [[kubernetes/cluster|Cluster]] - Minikube details

16
docs/reference/infrastructure/routing.md
View file

@ -59,21 +59,7 @@ DNS points to indri's Tailscale IP (100.98.163.89). TLS via Let's Encrypt (ACME
| 8096 | Jellyfin | HTTP | localhost | Media server |
| 44491 | K8s API | HTTPS | 0.0.0.0 | Minikube API server |
## Adding New Services
### Indri Services (via Caddy)
1. Host service on localhost
2. Add to `ansible/roles/caddy/defaults/main.yml`
3. Run `mise run provision-indri -- --tags caddy`
### K8s Services (via Tailscale Ingress)
1. Create manifests in `argocd/manifests/<service>/`
2. Add ArgoCD Application in `argocd/apps/`
3. Add Tailscale Ingress annotation
4. Add Caddy proxy entry
5. Sync via ArgoCD
## Related
- [[infrastructure/tailscale|Tailscale]] - ACL configuration
- [[infrastructure/hosts|Hosts]] - Where services run
- [[infrastructure/indri|Indri]] - Where services run

5
docs/reference/infrastructure/tailscale.md
View file

@ -13,11 +13,6 @@ Tailnet `tail8d86e.ts.net` provides secure networking for all BlumeOps infrastru
ACLs managed via Pulumi in `pulumi/policy.hujson`.
```bash
mise run tailnet-preview # Preview changes
mise run tailnet-up # Apply changes
```
## Groups
| Group | Members | Purpose |

18
docs/reference/kubernetes/apps.md
View file

@ -41,24 +41,6 @@ Registry of all applications deployed via [[services/argocd|ArgoCD]].
| `apps` | Automated | Picks up new Application manifests |
| All others | Manual | Explicit control over deployments |
## Common Commands
```bash
argocd app list # List all apps
argocd app get <app> # Get details
argocd app diff <app> # Preview changes
argocd app sync <app> # Deploy changes
```
## PR Workflow
1. Create feature branch, modify manifests
2. Push to forge
3. Sync apps application: `argocd app sync apps`
4. Point service at branch: `argocd app set <service> --revision feature/branch`
5. Test: `argocd app sync <service>`
6. After merge, reset: `argocd app set <service> --revision main`
## Related
- [[services/argocd|ArgoCD]] - GitOps platform details

40
docs/reference/kubernetes/cluster.md
View file

@ -6,7 +6,7 @@ tags:
# Kubernetes Cluster
Single-node Minikube cluster running on [[infrastructure/hosts|Indri]].
Single-node Minikube cluster running on [[infrastructure/indri|Indri]].
## Cluster Specifications
@ -22,50 +22,16 @@ Single-node Minikube cluster running on [[infrastructure/hosts|Indri]].
**Prerequisites:** Docker Desktop with at least 12GB memory allocated.
## Remote Access
From gilbert:
```bash
mise run ensure-minikube-indri-kubectl-config
```
Fish abbreviations:
- `ki` -> `kubectl --context=minikube-indri`
- `k9i` -> `k9s --context=minikube-indri`
## Volume Mounting
Pods mount NFS directly from [[storage/sifaka|Sifaka]]:
```yaml
volumes:
- name: torrents
nfs:
server: sifaka
path: /volume1/torrents
```
Docker NATs outbound traffic through indri's LAN IP (192.168.1.50), allowing access to Sifaka's NFS exports.
Pods mount NFS directly from [[storage/sifaka|Sifaka]]. Docker NATs outbound traffic through indri's LAN IP (192.168.1.50), allowing access to Sifaka's NFS exports.
## Registry Mirror
Containerd uses [[services/zot|Zot]] as a pull-through cache:
- Endpoint: `host.minikube.internal:5050`
- Config: `/etc/containerd/certs.d/<registry>/hosts.toml`
Containerd uses [[services/zot|Zot]] as a pull-through cache at `host.minikube.internal:5050`.
Mirrors configured: `registry.ops.eblu.me`, `docker.io`, `ghcr.io`, `quay.io`
## Useful Commands (on indri)
```bash
minikube status # Cluster status
minikube start # Start cluster
minikube stop # Stop cluster
minikube ssh # SSH into node
minikube logs # View logs
```
## Related
- [[kubernetes/apps|Apps]] - ArgoCD applications

24
docs/reference/services/1password.md
View file

@ -32,27 +32,9 @@ The `blumeops` vault contains all infrastructure credentials.
**ClusterSecretStore:** `onepassword-blumeops`
Services reference 1Password items via `ExternalSecret` manifests. Example: `argocd/manifests/devpi/external-secret.yaml`
## CLI Usage
```bash
# Get a secret field
op --vault blumeops item get <item-id> --fields <field> --reveal
# Inject into a template
op inject -i secret.yaml.tpl | kubectl apply -f -
```
## Bootstrap (Disaster Recovery)
1. Create Connect server: `op connect server create blumeops --vaults blumeops`
2. Create token: `op connect token create blumeops --server <id> --vault blumeops`
3. Store credentials in 1Password item "1Password Connect"
4. Apply bootstrap secret to k8s
5. Sync apps: 1password-connect, external-secrets-crds, external-secrets, external-secrets-config
Services reference 1Password items via `ExternalSecret` manifests.
## Related
- [[argocd|ArgoCD]] - Uses secrets for git access
- [[postgresql|PostgreSQL]] - Database credentials
- [[services/argocd|ArgoCD]] - Uses secrets for git access
- [[services/postgresql|PostgreSQL]] - Database credentials

15
docs/reference/services/argocd.md
View file

@ -26,19 +26,6 @@ GitOps continuous delivery platform for the [[kubernetes/cluster|Kubernetes clus
| `apps` | Automated | Picks up new Application manifests |
| All workloads | Manual | Explicit control over deployments |
## CLI Commands
```bash
# Login
argocd login argocd.ops.eblu.me --username admin --password "$(op ...)"
# Common operations
argocd app list
argocd app diff <app>
argocd app sync <app>
argocd app get <app>
```
## Credentials
- Admin password: 1Password (blumeops vault)
@ -47,4 +34,4 @@ argocd app get <app>
## Related
- [[kubernetes/apps|Apps]] - Full application registry
- [[forgejo|Forgejo]] - Git source
- [[services/forgejo|Forgejo]] - Git source

18
docs/reference/services/forgejo.md
View file

@ -38,21 +38,11 @@ Git forge and CI/CD platform. **Primary source of truth for blumeops** (mirrored
**Workflows:** `.forgejo/workflows/`
- `build-container.yaml` - Container image builds on tag
**Container release:**
```bash
mise run container-list # List containers
mise run container-release runner v1.0.0 # Tag and build
```
## Secrets
## Ansible Management
```bash
mise run provision-indri -- --tags forgejo
```
Secrets fetched from 1Password: `lfs-jwt-secret`, `internal-token`, `oauth2-jwt-secret`, `runner_reg`
Managed via 1Password: `lfs-jwt-secret`, `internal-token`, `oauth2-jwt-secret`, `runner_reg`
## Related
- [[argocd|ArgoCD]] - Uses Forgejo as git source
- [[zot|Zot]] - Container registry for built images
- [[services/argocd|ArgoCD]] - Uses Forgejo as git source
- [[services/zot|Zot]] - Container registry for built images

18
docs/reference/services/miniflux.md
View file

@ -17,7 +17,7 @@ Minimalist RSS/Atom feed reader.
| **Tailscale URL** | https://feed.tail8d86e.ts.net |
| **Namespace** | `miniflux` |
| **Image** | `ghcr.io/miniflux/miniflux:latest` |
| **Database** | [[postgresql|PostgreSQL]] |
| **Database** | [[services/postgresql|PostgreSQL]] |
## Features
@ -29,21 +29,13 @@ Minimalist RSS/Atom feed reader.
## Database
Uses CloudNativePG cluster at `pg.ops.eblu.me`.
Database user password stored in `blumeops-pg-app` secret (auto-generated by CNPG).
Uses CloudNativePG cluster at `pg.ops.eblu.me`. Database user password stored in `blumeops-pg-app` secret (auto-generated by CNPG).
## Backup
Feed subscriptions and read state backed up via [[borgmatic|Borgmatic]] PostgreSQL hook.
## Health Check
```bash
curl https://feed.ops.eblu.me/healthcheck
```
Feed subscriptions and read state backed up via [[services/borgmatic|Borgmatic]] PostgreSQL hook.
## Related
- [[postgresql|PostgreSQL]] - Database backend
- [[borgmatic|Borgmatic]] - Data backup
- [[services/postgresql|PostgreSQL]] - Database backend
- [[services/borgmatic|Borgmatic]] - Data backup

12
docs/reference/services/navidrome.md
View file

@ -36,17 +36,7 @@ The `/data` directory contains SQLite database, configuration, and cache.
| `ND_MUSICFOLDER` | /music |
| `ND_DATAFOLDER` | /data |
## Initial Setup
On first access, Navidrome prompts to create an admin user. No default credentials.
## Verify NFS Mount
```bash
kubectl --context=minikube-indri -n navidrome exec deploy/navidrome -- ls /music
```
## Related
- [[jellyfin|Jellyfin]] - Video streaming
- [[services/jellyfin|Jellyfin]] - Video streaming
- [[storage/sifaka|Sifaka]] - Music storage

23
docs/reference/services/postgresql.md
View file

@ -23,8 +23,8 @@ Database cluster via CloudNativePG operator.
| Database | Owner | Purpose |
|----------|-------|---------|
| miniflux | miniflux | [[miniflux|Miniflux]] feed data |
| teslamate | teslamate | [[teslamate|TeslaMate]] vehicle data |
| miniflux | miniflux | [[services/miniflux|Miniflux]] feed data |
| teslamate | teslamate | [[services/teslamate|TeslaMate]] vehicle data |
## Users
@ -34,20 +34,11 @@ Database cluster via CloudNativePG operator.
| miniflux | app owner | Owns miniflux database |
| teslamate | superuser | TeslaMate (needs extensions) |
| eblume | superuser | Admin access |
| borgmatic | pg_read_all_data | [[borgmatic|Backup]] access |
## Quick Connect
```bash
PGPASSWORD=$(op --vault blumeops item get <item-id> --fields password --reveal) \
psql -h pg.ops.eblu.me -U eblume -d miniflux
```
| borgmatic | pg_read_all_data | [[services/borgmatic|Backup]] access |
## Backup
Backed up via [[borgmatic|Borgmatic]] `postgresql_databases` hook.
Borgmatic streams `pg_dump` directly to Borg (no intermediate files, no downtime).
Backed up via [[services/borgmatic|Borgmatic]] `postgresql_databases` hook. Streams `pg_dump` directly to Borg (no intermediate files, no downtime).
## Credentials
@ -63,6 +54,6 @@ Borgmatic streams `pg_dump` directly to Borg (no intermediate files, no downtime
## Related
- [[miniflux|Miniflux]] - Feed reader database
- [[teslamate|TeslaMate]] - Vehicle data database
- [[borgmatic|Borgmatic]] - Database backup
- [[services/miniflux|Miniflux]] - Feed reader database
- [[services/teslamate|TeslaMate]] - Vehicle data database
- [[services/borgmatic|Borgmatic]] - Database backup

27
docs/reference/services/prometheus.md
View file

@ -18,37 +18,24 @@ Metrics storage and querying for BlumeOps infrastructure.
| **Namespace** | `monitoring` |
| **Image** | `prom/prometheus:v3.2.1` |
| **Storage** | 50Gi PVC |
| **Manifests** | `argocd/manifests/prometheus/` |
## Data Sources
### Remote Write (from Alloy)
- Indri system metrics via [[alloy|Alloy]] remote_write
- Indri system metrics via [[services/alloy|Alloy]] remote_write
- Textfile metrics: minikube, borgmatic, zot, jellyfin
### Scrape Targets
| Target | Metrics |
|--------|---------|
| `sifaka:9100` | [[storage/sifaka|Sifaka]] NAS (node_exporter) |
| `cnpg-metrics.tail8d86e.ts.net:9187` | [[postgresql|CloudNativePG]] metrics |
| `cnpg-metrics.tail8d86e.ts.net:9187` | [[services/postgresql|CloudNativePG]] metrics |
| `kube-state-metrics.monitoring.svc:8080` | Kubernetes resource metrics |
## Query API
```bash
# Check targets
curl -s https://prometheus.ops.eblu.me/api/v1/targets | jq '.data.activeTargets[].scrapeUrl'
```
## ArgoCD Management
```bash
argocd app sync prometheus
```
Manifests: `argocd/manifests/prometheus/`
## Related
- [[alloy|Alloy]] - Metrics collector
- [[grafana|Grafana]] - Visualization
- [[loki|Loki]] - Logs counterpart
- [[services/alloy|Alloy]] - Metrics collector
- [[services/grafana|Grafana]] - Visualization
- [[services/loki|Loki]] - Logs counterpart

28
docs/reference/services/zot.md
View file

@ -30,37 +30,13 @@ OCI-native container registry providing pull-through cache and private image sto
## Pull-Through Cache
When [[kubernetes/cluster|minikube]] pulls an image:
1. Containerd checks zot first (`host.minikube.internal:5050`)
2. If cached, returns immediately
3. If not, zot fetches from upstream, caches, returns
## Private Images
```bash
# Build and push from gilbert
podman build -t registry.ops.eblu.me/blumeops/myapp:v1 .
podman push registry.ops.eblu.me/blumeops/myapp:v1
# Use in k8s manifest
image: registry.ops.eblu.me/blumeops/myapp:v1
```
When [[kubernetes/cluster|minikube]] pulls an image, containerd checks zot first. If cached, returns immediately. If not, zot fetches from upstream, caches it, then returns.
## Security Model
Network access only (no authentication). Defense is the Tailscale ACL boundary.
## Useful Commands
```bash
# List all images
curl -s http://indri:5050/v2/_catalog | jq
# List tags
curl -s http://indri:5050/v2/blumeops/devpi/tags/list | jq
```
## Related
- [[forgejo|Forgejo]] - Container build CI
- [[services/forgejo|Forgejo]] - Container build CI
- [[kubernetes/cluster|Cluster]] - Registry consumer

15
docs/reference/storage/backups.md
View file

@ -7,7 +7,7 @@ tags:
# Backup Policy
Daily automated backups from [[infrastructure/hosts|Indri]] to [[storage/sifaka|Sifaka]] NAS.
Daily automated backups from [[infrastructure/indri|Indri]] to [[storage/sifaka|Sifaka]] NAS.
## Schedule
@ -64,19 +64,6 @@ Metrics exposed to [[services/prometheus|Prometheus]]:
Dashboard: "Borgmatic Backups" in [[services/grafana|Grafana]]
## Recovery
```bash
# List archives
ssh indri 'mise x -- borgmatic list'
# Extract specific path from latest
ssh indri 'mise x -- borgmatic extract --archive latest --path /some/path'
# Check repository health
ssh indri 'mise x -- borgmatic check'
```
## Related
- [[services/borgmatic|Borgmatic]] - Backup system details