Add Phase 3 tutorials with audience targeting (#94)
## Summary - Create tutorials directory structure with index page - Add 5 main tutorials targeting different audiences: - **what-is-blumeops** (Reader, AI) - High-level orientation - **exploring-the-docs** (All) - Navigation guide - **ai-assistance-guide** (AI, Owner) - Context for AI-assisted operations - **contributing** (Contributor) - First contribution workflow - **replicating-blumeops** (Replicator) - Overview for building similar setup - Add 4 replication sub-tutorials: - tailscale-setup, kubernetes-bootstrap, argocd-config, observability-stack - Update README.md to mark Phase 3 complete - Add changelog fragment Each tutorial explicitly identifies its target audiences and links to reference material rather than re-explaining concepts. ## Deployment and Testing - [x] All pre-commit hooks pass (doc-links validates wiki links) - [ ] Build docs via workflow to verify rendering - [ ] Review content for accuracy 🤖 Generated with [Claude Code](https://claude.com/claude-code) Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/94
This commit is contained in:
parent
bf03d71780
commit
7ebac4aef6
20 changed files with 1864 additions and 10 deletions
113
docs/tutorials/replication/core-services.md
Normal file
113
docs/tutorials/replication/core-services.md
Normal file
|
|
@ -0,0 +1,113 @@
|
|||
---
|
||||
title: core-services
|
||||
tags:
|
||||
- tutorials
|
||||
- replication
|
||||
- forgejo
|
||||
---
|
||||
|
||||
# Core Services Setup
|
||||
|
||||
> **Audiences:** Replicator
|
||||
|
||||
This tutorial walks through setting up the foundational services that your GitOps infrastructure depends on: a git forge and optionally a container registry.
|
||||
|
||||
## Why Core Services First?
|
||||
|
||||
Before Kubernetes and ArgoCD, you need somewhere to store your infrastructure definitions. [[forgejo]] provides:
|
||||
- Git hosting for your GitOps repository
|
||||
- CI/CD workflows for building and deploying
|
||||
- A web interface for code review and PRs
|
||||
|
||||
The [[zot]] container registry is optional but useful for hosting your own container images.
|
||||
|
||||
## Step 1: Install Forgejo
|
||||
|
||||
Forgejo runs directly on your server (not in Kubernetes) because Kubernetes depends on it.
|
||||
|
||||
### Using Ansible (BlumeOps Approach)
|
||||
|
||||
BlumeOps manages Forgejo via an Ansible role. See [[reference/ansible/roles | Ansible Roles]].
|
||||
|
||||
### Manual Installation
|
||||
|
||||
1. Download Forgejo from [forgejo.org](https://forgejo.org/download/)
|
||||
2. Create a service user and directories
|
||||
3. Configure with `app.ini`
|
||||
4. Set up as a system service
|
||||
|
||||
Key configuration points:
|
||||
- SSH on a non-standard port (e.g., 2222) to avoid conflicts
|
||||
- Database (SQLite works fine for personal use)
|
||||
- Domain and URL settings for your Tailscale hostname
|
||||
|
||||
## Step 2: Configure SSH Access
|
||||
|
||||
Set up SSH for git operations:
|
||||
|
||||
```bash
|
||||
# Add your SSH key to Forgejo via the web UI
|
||||
# Then test access:
|
||||
ssh -T git@your-server.tailnet.ts.net -p 2222
|
||||
```
|
||||
|
||||
## Step 3: Create Your GitOps Repository
|
||||
|
||||
1. Create a new repository in Forgejo (e.g., `infrastructure` or `homelab`)
|
||||
2. Initialize the standard directory structure:
|
||||
|
||||
```
|
||||
your-repo/
|
||||
├── ansible/ # Host configuration
|
||||
│ ├── playbooks/
|
||||
│ └── roles/
|
||||
├── argocd/ # Kubernetes GitOps
|
||||
│ ├── apps/ # ArgoCD Applications
|
||||
│ └── manifests/ # K8s manifests per service
|
||||
├── pulumi/ # IaC for Tailscale, DNS
|
||||
└── docs/ # Documentation
|
||||
```
|
||||
|
||||
3. Push your initial commit
|
||||
|
||||
## Step 4: Set Up CI/CD Runner (Optional)
|
||||
|
||||
Forgejo Actions runs workflows defined in `.forgejo/workflows/`. To use it:
|
||||
|
||||
1. Register a runner on your server
|
||||
2. Configure runner to access your build tools
|
||||
3. Create workflow files for builds and deployments
|
||||
|
||||
BlumeOps runs a Forgejo runner in Kubernetes - see [[forgejo]] for details.
|
||||
|
||||
## Step 5: Container Registry (Optional)
|
||||
|
||||
If you'll build custom container images, set up [[zot]]:
|
||||
|
||||
1. Install Zot on your server
|
||||
2. Configure authentication
|
||||
3. Set up TLS (via Caddy or similar)
|
||||
|
||||
For getting started, you can skip this and use public registries.
|
||||
|
||||
## What You Now Have
|
||||
|
||||
- Git hosting for infrastructure code
|
||||
- SSH access for git operations
|
||||
- Foundation for CI/CD workflows
|
||||
- Optionally, a private container registry
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [[tutorials/replication/kubernetes-bootstrap | Bootstrap Kubernetes]] - Now that you have a git repo, set up your cluster
|
||||
- Configure Forgejo webhooks for ArgoCD (after ArgoCD is running)
|
||||
|
||||
## BlumeOps Specifics
|
||||
|
||||
BlumeOps' Forgejo setup includes:
|
||||
- Ansible role for installation and updates
|
||||
- SSH on port 2222, proxied via Caddy
|
||||
- Integration with ArgoCD via deploy keys
|
||||
- Forgejo runner in Kubernetes for CI/CD
|
||||
|
||||
See [[forgejo]] and [[zot]] for full details.
|
||||
Loading…
Add table
Add a link
Reference in a new issue