eblume/blumeops
1
1
Fork 0
Code Issues Pull requests Projects Releases 83 Packages Wiki Activity Actions
blumeops/docs/tutorials/replicating-blumeops.md
Erich Blume 4f0476a851
All checks were successful
Build Container / detect (push) Successful in 3s
Details
Build Container (Nix) / detect (push) Successful in 1s
Details
Build Container (Nix) / build (quartz) (push) Successful in 1s
Details
Build Container / build (quartz) (push) Successful in 10s
Details
Fix spider trap: disable SPA mode, remove index files, relax wiki-links (#290) 
## Summary

Fixes the Facebook crawler spider trap that's been generating infinite recursive URLs like `/how-to/tutorials/tutorials/how-to/explanation/...` for several days.

**Root cause:** Quartz SPA mode + nginx `try_files` fallback to `index.html` meant any fabricated URL returned the root HTML shell with HTTP 200. Crawlers followed relative links from those fake URLs, creating infinite recursion.

**Fix:**
- Disable Quartz SPA mode (`enableSPA: false`) — all pages are now fully static HTML
- Replace nginx SPA fallback with `=404` + Quartz's static `404.html`
- Remove `robots.txt` exclusions (no longer needed)

**Docs cleanup (Obsidian.nvim compat no longer needed):**
- Delete hand-curated category index files (`tutorials.md`, `reference.md`, `how-to.md`, `explanation.md`) — Quartz auto-generates folder pages
- Delete `postgresql-storage.md` (redirect stub) and `migrate-forgejo-from-brew.md` (stale history)
- Drop `docs-check-index` and `docs-check-filenames` prek hooks
- Rewrite `docs-check-links` to allow path-based wiki-links (`[[path/to/file]]`) and only error on true ambiguity
- Add `ai-docs` doc tree listing to replace index files for AI context
- Add natural cross-links from reference cards to fix orphan docs

## Deployment and Testing

- [ ] Merge and let the build pipeline run
- [ ] Verify docs.eblu.me serves pages correctly with full page loads
- [ ] Verify non-existent URLs return 404
- [ ] Monitor crawler traffic — should drop to near zero for fabricated URLs

Reviewed-on: #290
2026-03-09 11:59:43 -07:00

4 KiB
Raw Blame History

title modified tags
Replicating BlumeOps 2026-02-07
tutorials
replication

Replicating BlumeOps

Audiences: Replicator

This tutorial provides a roadmap for building your own homelab GitOps environment inspired by BluemeOps. It links to detailed component tutorials for each major piece.

What You'll Build

By following this guide, you'll have:

  • A secure mesh network connecting your devices
  • A Kubernetes cluster for running containerized services
  • GitOps-driven deployments via ArgoCD
  • Observability with metrics, logs, and dashboards
  • Backup and disaster recovery capabilities

Hardware Requirements

BluemeOps runs on modest hardware. At minimum:

Component BlumeOps Uses Minimum Alternative
Server Mac Mini M1 Any machine with sufficient RAM (16GB recommended)
NAS Synology DS920+ USB drive or second machine
Workstation MacBook Air M4 Whatever you use daily

You can start with a single machine and add storage later.

The Journey

Phase 1: Networking Foundation

Before deploying services, establish secure connectivity.

tailscale-setup

  • Create a tailnet and connect your devices
  • Configure ACLs for service access
  • Set up MagicDNS for convenient naming

This replaces: traditional VPNs, port forwarding, dynamic DNS

Phase 2: Core Services

Bootstrap the essential services that everything else depends on.

core-services

  • Set up forgejo for git hosting and CI/CD
  • Optionally set up zot container registry
  • Configure SSH access and deploy keys

Forgejo is central to GitOps - it's where your infrastructure definitions live and where CI/CD workflows run.

Phase 3: Kubernetes Cluster

A cluster for running containerized workloads.

kubernetes-bootstrap

  • Install minikube (or k3s, kind, etc.)
  • Configure persistent storage
  • Expose the API securely via Tailscale

BlumeOps uses minikube for simplicity, but the patterns apply to any distribution.

Phase 4: GitOps with ArgoCD

Declarative, git-driven deployments.

argocd-config

  • Install ArgoCD in your cluster
  • Connect to your git repository
  • Deploy your first application
  • Set up the app-of-apps pattern

This is the heart of GitOps - changes in git automatically sync to your cluster.

Phase 5: Observability Stack

Know what's happening in your infrastructure.

observability-stack

  • Deploy Prometheus for metrics
  • Deploy Loki for logs
  • Deploy Grafana for dashboards
  • Configure Alloy for collection

Without observability, you're flying blind.

Phase 6: Your First Services

With the foundation in place, deploy actual workloads. BluemeOps runs:

Pick what matters to you. Each service follows similar patterns:

  1. Create Kubernetes manifests
  2. Create ArgoCD Application
  3. Configure ingress routing
  4. Sync and verify

Phase 7: Backups and Resilience

Protect your data.

  • Set up borgmatic for backup automation
  • Configure NAS as backup target
  • Test restore procedures
  • Document disaster recovery

Alternative Approaches

BluemeOps makes specific choices that may not suit everyone:

BlumeOps Choice Alternative
macOS server Linux server (more common)
Minikube k3s, kind, or managed K8s
Tailscale WireGuard, Nebula
ArgoCD Flux, manual kubectl
Ansible NixOS, Docker Compose

The principles (GitOps, IaC, observability) matter more than specific tools.

Getting Started

Begin with tailscale-setup - networking is the foundation everything else builds on.

Related