chore: add CLAUDE.md

2025-08-19 16:32:48 +09:00
parent 8298ec0223
commit b1c844d978
2 changed files with 138 additions and 1 deletions
--- a/.gitignore
+++ b/.gitignore
@@ -138,4 +138,4 @@ dist
 /.env.local*
 /custom.just
 /custom/
-transcript*
+/private/
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -0,0 +1,137 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Overview
+
+buun-stack is a Kubernetes development stack for self-hosted environments with enterprise-grade components (k3s, Vault, Keycloak, PostgreSQL, Longhorn) orchestrated through Just task runner recipes.
+
+## Essential Commands
+
+### Development Setup
+
+```bash
+mise install           # Install all required tools
+just env::setup        # Interactive environment configuration
+just                   # Show all available commands
+```
+
+### Core Installation Sequence
+
+```bash
+just k8s::install              # Deploy k3s cluster
+just longhorn::install         # Storage layer
+just vault::install            # Secrets management
+just postgres::install         # Database cluster
+just keycloak::install         # Identity provider
+just keycloak::create-realm    # Initialize realm
+just vault::setup-oidc-auth    # Configure Vault OIDC
+just k8s::setup-oidc-auth      # Enable k8s OIDC auth
+```
+
+### Common Operations
+
+```bash
+# User management
+just keycloak::create-user                    # Interactive user creation
+just keycloak::add-user-to-group <user> <group>
+
+# Secret management
+just vault::put <path> <key>=<value>          # Store secret (OIDC auth)
+just vault::get <path> <field>                # Retrieve secret
+
+# Database
+just postgres::create-db <name>               # Create database
+just postgres::psql                           # PostgreSQL shell
+
+# Testing/validation
+kubectl --context <host>-oidc get nodes       # Test OIDC auth
+```
+
+## Architecture & Key Patterns
+
+### Module Organization
+
+- **Justfiles**: Each module has its own justfile with focused recipes
+- **TypeScript Scripts**: `/keycloak/scripts/` contains Keycloak Admin API automation
+- **Templates**: `*.gomplate.yaml` files use environment variables from `.env.local`
+- **Custom Extensions**: `custom.just` can be created for additional workflows
+
+### Authentication Flow
+
+1. Keycloak provides OIDC identity for all services
+2. Vault uses Keycloak for authentication via OIDC
+3. Kubernetes API server validates tokens against Keycloak
+4. All OIDC users automatically get cluster-admin role
+
+### Environment Variables
+
+The `.env.local` file (created by `just env::setup`) contains critical configuration:
+
+- `LOCAL_K8S_HOST`: Internal SSH hostname
+- `EXTERNAL_K8S_HOST`: External FQDN for k8s API  
+- `KEYCLOAK_HOST`: Keycloak FQDN
+- `VAULT_HOST`: Vault FQDN
+- `KEYCLOAK_REALM`: Realm name (default: buunstack)
+
+### TypeScript Utilities
+
+All scripts in `/keycloak/scripts/` follow this pattern:
+
+- Use `@keycloak/keycloak-admin-client` for API operations
+- Validate environment with `tiny-invariant`
+- Load config from `.env.local` using `@dotenvx/dotenvx`
+- Execute with `tsx` runtime
+
+### Credential Storage Pattern
+
+Credentials are automatically generated and stored in Vault:
+
+```bash
+# Example: PostgreSQL superuser password
+just vault::get secret/postgres/superuser password
+```
+
+### Important Considerations
+
+1. **Root Token**: Vault root token is required for initial setup. Store securely or use 1Password reference.
+
+2. **OIDC Configuration**: When creating services that need authentication:
+   - Create Keycloak client with `just keycloak::create-client`
+   - Configure service to use `https://${KEYCLOAK_HOST}/realms/${KEYCLOAK_REALM}`
+
+3. **Cloudflare Tunnel**: Required hostnames must be configured with "no TLS verify" for self-signed certificates:
+   - `ssh.domain` → SSH localhost:22
+   - `vault.domain` → HTTPS localhost:443
+   - `auth.domain` → HTTPS localhost:443
+   - `k8s.domain` → HTTPS localhost:6443
+
+4. **Helm Values**: All Helm charts use gomplate templates for dynamic configuration based on environment variables.
+
+5. **Cleanup Operations**: Most modules provide cleanup recipes (e.g., `just keycloak::delete-user`) with confirmation prompts.
+
+## Testing and Validation
+
+After setup, validate the stack:
+
+```bash
+# Test Kubernetes OIDC auth
+kubectl --context <host>-oidc get nodes
+
+# Test Vault OIDC auth
+vault login -method=oidc
+vault kv get secret/test
+
+# Check service health
+kubectl get pods -A
+```
+
+## Development Workflow
+
+When adding new services:
+
+1. Create module directory with justfile
+2. Add gomplate templates for Helm values if needed
+3. Store credentials in Vault using established patterns
+4. Create Keycloak client if authentication required
+5. Import module in main justfile