How-To Guide

Setup kup6s Workspace¶

Type: How-To (Task-oriented)

Related: Workspace Structure | Access kubectl

Prerequisites¶

Git installed (v2.20+)
SSH keys configured for:
- git.bluedynamics.eu
- github.com (optional, for mirrors)
Access to kup6s repositories (ask team admin)
Disk space: ~500MB for all repos

Quick Start (TL;DR)¶

git clone git@git.bluedynamics.eu:kup6s/workspace-kup6s.git kup6s
cd kup6s
./scripts/clone-all.sh

Done! All repositories cloned and ready.

Detailed Steps¶

Step 1: Clone Workspace Repository¶

The workspace repository is a lightweight meta repository containing automation scripts and workspace-level files.

# Clone workspace repo
git clone git@git.bluedynamics.eu:kup6s/workspace-kup6s.git kup6s
cd kup6s

# Verify workspace files exist
ls -la
# Should see: CLAUDE.md, README.md, repos.yaml, scripts/

What You Just Cloned:

Workspace metadata and automation
NOT the actual infrastructure code (that comes next)

Step 2: Clone All Subrepos¶

Run the automation script to clone all infrastructure repositories:

./scripts/clone-all.sh

Expected Output:

=== Cloning repositories from /home/you/kup6s/repos.yaml ===

Cloning argoapps...
✓ argoapps cloned successfully

Cloning documentation...
✓ documentation cloned successfully

Cloning dp-infra...
✓ dp-infra cloned successfully

Cloning kube-hetzner...
✓ kube-hetzner cloned successfully

=== All repositories processed ===

What Happened:

Script read repos.yaml configuration
Cloned 4 independent git repositories:
- argoapps/ - ArgoCD application definitions
- documentation/ - This documentation
- dp-infra/ - Infrastructure deployments (GitLab, etc.)
- kube-hetzner/ - Cluster provisioning config

Step 3: Verify Setup¶

Check that all repos were cloned successfully:

./scripts/status-all.sh

Expected Output:

=== Git status for all repositories ===

=== workspace (meta repository) ===
Branch: main
Working tree clean

=== argoapps ===
Branch: main
Working tree clean

=== documentation ===
Branch: main
Working tree clean

=== dp-infra ===
Branch: main
Working tree clean

=== kube-hetzner ===
Branch: main
Working tree clean

If any repo shows “⚠️ Repository not cloned”, re-run ./scripts/clone-all.sh.

Step 4: Configure Individual Repositories¶

Each repository may have additional setup requirements:

kube-hetzner/ (Cluster Config)¶

Requires environment variables for credentials:

cd kube-hetzner

# Copy example environment file
cp .env.example .env

# Edit .env and add your credentials
vim .env  # or your preferred editor

# Add:
# - Hetzner Cloud API token
# - Hetzner DNS API token  
# - S3 credentials
# - SMTP credentials
# - etc.

IMPORTANT: Never commit .env file (it’s in .gitignore).

argoapps/ (ArgoCD Apps)¶

Requires npm dependencies:

cd argoapps
npm install

documentation/ (This Docs)¶

Requires mxmake build system:

cd documentation

# Install mxmake if not already installed
pip install mxmake

# Build documentation
make docs

# Or run development server
make docs-live  # http://localhost:8000

dp-infra/ (Infrastructure Deployments)¶

Each subdirectory is independent. For example, GitLab BDA:

cd dp-infra/gitlabbda
npm install

Common Operations¶

Update All Repositories¶

Pull latest changes from origin for all repos:

cd /path/to/kup6s  # Workspace root
./scripts/update-all.sh

What It Does:

Checks each repo for uncommitted changes
Skips repos with local modifications (safety)
Pulls latest from origin/<branch>
Reports update status

Output Example:

=== Updating repositories ===

Updating argoapps...
Already up to date.
✓ argoapps updated successfully

Updating documentation...
⚠️  documentation has uncommitted changes - skipping update

...

Check Status Across All Repos¶

See git status for workspace and all subrepos:

./scripts/status-all.sh

Useful for:

Finding repos with uncommitted changes
Checking which branch you’re on
Seeing if you’re ahead/behind remote

Work on Specific Repository¶

Each repository is independent - work normally:

# Example: Add new ArgoCD application
cd argoapps
git checkout -b add-myapp
vim apps/infra/myapp.ts
npm run build
git add .
git commit -m "Add myapp deployment"
git push origin add-myapp

# Create PR on GitLab/GitHub

Key Point: Changes in subrepos don’t affect workspace repo (they’re independent).

Troubleshooting¶

Problem: “Permission denied (publickey)”¶

Cause: SSH key not configured for git.bluedynamics.eu

Solution:

# Check if SSH key is added
ssh -T git@git.bluedynamics.eu

# If fails, add your public key to GitLab:
# 1. Copy your public key
cat ~/.ssh/id_rsa.pub  # or id_ed25519.pub

# 2. Add to GitLab: Profile → SSH Keys → Paste key

Problem: “Repository does not exist”¶

Cause: You don’t have access to a repository

Solution: Contact team admin to grant access to:

kup6s/workspace
kup6s/argoapps
kup/redblue/documentation
kup6s/dp/dp-infra
kup6s/kube-hetzner

Problem: clone-all.sh shows “⚠️ already exists”¶

Not an error! The script skips already-cloned repos.

If you need to re-clone:

rm -rf <repo-name>
./scripts/clone-all.sh

Problem: update-all.sh skips a repo¶

Cause: Repo has uncommitted changes (safety feature)

Solution:

cd <repo-name>
git status  # See what's uncommitted

# Either commit changes or stash them
git stash  # Temporarily save changes
cd ..
./scripts/update-all.sh  # Now it will update
cd <repo-name>
git stash pop  # Restore changes

Next Steps¶

Access the Cluster¶

See Access kubectl to configure kubectl:

export KUBECONFIG=kube-hetzner/kup6s_kubeconfig.yaml
kubectl get nodes

Understand the Architecture¶

Workspace Structure - Why meta repository?
Infrastructure as Code - IaC philosophy
Why kube-hetzner - Technology choices

Make Your First Change¶

See repository-specific guides:

Apply Infrastructure Changes - Modify cluster config
Deploy First App - Add ArgoCD application

Reference¶

Workspace Files¶

CLAUDE.md - Development guidelines for AI assistants
README.md - Workspace overview and quick reference
repos.yaml - Repository metadata (URLs, branches, descriptions)
scripts/ - Automation scripts
- clone-all.sh - Clone all repos
- update-all.sh - Update all repos
- status-all.sh - Show status

Repository URLs¶

Workspace: git@git.bluedynamics.eu:kup6s/workspace-kup6s.git
argoapps: git@git.bluedynamics.eu:kup6s/argoapps.git
documentation: git@git.bluedynamics.eu:kup/redblue/documentation.git
dp-infra: git@git.bluedynamics.eu:kup6s/dp/dp-infra.git
kube-hetzner: git@git.bluedynamics.eu:kup6s/kube-hetzner.git

Questions? Open an issue in the workspace repository or ask in team chat.