mojosa-services

A try to move away from systemd based configuration to the better deployment models, specifically k3s.

🛠️ Useful Commands & Local Development Guide

This project uses Kustomize to manage multiple isolated instances of the mycowiki application on a local k3s cluster.

⚠️ k3s Local Development Gotchas

Before running the commands below, keep these k3s-specific quirks in mind:

1. Image Importing: k3s uses containerd, not Docker. You must manually export and import your Docker image every time you rebuild it.
2. Namespaces: Kustomize's namespace: directive only rewrites the namespace in your YAML files; it does not create the Kubernetes Namespace object. You must create them manually.
3. Networking: k3s NodePorts do not bind to localhost (127.0.0.1) by default. You must access the app via your machine's LAN IP (e.g., 192.168.x.x), or use kubectl port-forward.
4. Image Pull Policy: Because mycowiki:local doesn't exist on Docker Hub, ensure your deployment.yaml uses imagePullPolicy: Never to prevent k3s from endlessly trying to download it from the internet.

---

📦 Image Build & Import

Run these commands from the directory containing your Dockerfile whenever you update the Go code.

# 1. Build the image using Docker
docker build -t mycowiki:local .

# 2. Export the image to a tarball
docker save mycowiki:local -o /tmp/mycowiki.tar

# 3. Import the tarball into k3s's containerd
sudo k3s ctr images import /tmp/mycowiki.tar

# 4. Verify the image is successfully loaded
sudo k3s ctr images ls | grep mycowiki

---

🚀 Deployment & Namespaces

# Validate Kustomize output before applying (catches YAML errors early)
kustomize build wikis/root/

# Create the namespaces (Required before applying Kustomize configs)
kubectl create namespace wiki-personal
kubectl create namespace wiki-software

# Apply the Kustomize overlays to the cluster
kubectl apply -k wikis/root/
kubectl apply -k wikis/software/

# Restart a deployment (e.g., after changing configs or env vars)
kubectl rollout restart deployment/personal-wiki -n wiki-personal

---

👀 Monitoring & Status

# Watch pods in real-time as they start up (Ctrl+C to exit)
kubectl get pods -n wiki-personal -w

# Show all resources and Persistent Volume Claims (PVCs) in a namespace
kubectl get all,pvc -n wiki-personal

# Check if the Service is successfully wired to a Pod (should show an IP, not <none>)
kubectl get endpoints -n wiki-personal

# View application logs (useful if the pod is crashing)
kubectl logs -n wiki-personal deployment/personal-wiki

# Detailed info about a pod (useful when stuck in ContainerCreating)
kubectl describe pod -n wiki-personal -l app=wiki

# Detailed info about a PVC (useful when storage won't bind)
kubectl describe pvc personal-wiki-data -n wiki-personal

---

🌐 Networking & Access

# Get your LAN IP address (NodePorts are bound to this, not localhost)
hostname -I | awk '{print $1}'

# Access your wikis in the browser using the IP from the command above:
#   Personal Wiki: http://<your-lan-ip>:30081
#   Software Wiki: http://<your-lan-ip>:30082

# ALTERNATIVE: Bypass NodePort entirely and tunnel directly to the pod via localhost
kubectl port-forward svc/personal-wiki 8080:1737 -n wiki-personal
# Then open: http://localhost:8080 in your browser

---

🔧 Troubleshooting

Internet dropouts while k3s is running? This usually happens if your home router uses the 10.42.x.x or 10.43.x.x subnets, which conflict with k3s defaults.

# Check your router's default gateway IP
ip route | grep default

# Test raw connectivity vs DNS
ping -c 3 8.8.8.8        # Should work
ping -c 3 google.com     # If this fails, it's a DNS/routing conflict

Fixing IP Overlap: If your router uses 10.42.x.x, reinstall k3s with non-conflicting CIDRs:

sudo /usr/local/bin/k3s-uninstall.sh
curl -sfL https://get.k3s.io | sh -s - \
  --cluster-cidr 172.20.0.0/16 \
  --service-cidr 172.21.0.0/16

---

🧹 Cleanup

# Delete a specific wiki and all its resources (PVCs, Services, Deployments)
kubectl delete namespace wiki-personal

# Uninstall k3s entirely from the machine
sudo /usr/local/bin/k3s-uninstall.sh