Skip to content

Home

Jump to bottom
Jorge S. Cuesta edited this page Jun 30, 2025 · 6 revisions

OUT OF DATE HOME PAGE

We will update it as soon as we release it!

🚀 Getting Started

This guide walks you through setting up the local development environment from scratch using k3d, tilt, and CloudNativePG.

🔧 Prerequisites

Before continuing, make sure you have the following installed:

Tilt cluster notes

Tilt supports multiple clusters and they have different levels of difficulty. See this page for more details.

🏗️ Step 1: Create the Local Kubernetes Cluster

Create a k3d cluster named igniter with a local container registry.

k3d cluster create igniter --registry-create igniter-registry

Verify it's working:

kubectl get nodes

The output is something like this:

NAME                   STATUS   ROLES                  AGE   VERSION
k3d-igniter-server-0   Ready    control-plane,master   16s   v1.31.5+k3s1

📦 Step 2: Install the CloudNativePG Operator

The operator version is vendored in the repo under:

deploy/postgres/operator

Install it with:

kubectl apply --server-side -f deploy/postgres/operator

You can confirm it is running:

kubectl get pods -n cnpg-system

You should see a pod like cloudnative-pg-controller-manager-xxxx in a Running state.

NAME                                       READY   STATUS    RESTARTS   AGE
cnpg-controller-manager-5d478566fb-z29x5   1/1     Running   0          33s

🎛️ Step 3: Start Tilt

Run:

tilt up

Tilt will:

  • Generate a TLS certificate and a postgres-tls Kubernetes secret (if not already present)
  • Generate a random PostgreSQL password and write it to postgres-secrets.yml
  • Create a Kubernetes secret named postgres-secrets
  • Create a postgres-middleman-connection secret with a full DATABASE_URL pointing at your cluster
  • Apply the Postgres dev cluster and wait for readiness
  • Build the middleman Docker image locally via the Dockerfile at deploy/middleman/middleman.dockerfile
  • Apply Kubernetes manifests under deploy/middleman/dev
  • Start port-forwards:
    • Postgres: localhost:5432 → cluster
    • Middleman: localhost:3000 → container

Once services are up, you'll see logs and status updates in Tilt's dashboard.

📂 Directory Structure Overview

Here are some key folders you'll be working with:

  • apps/middleman → Your Next.js app (Next 15)
  • deploy/postgres → Postgres dev cluster resources
  • deploy/postgres/operator → CloudNativePG manifests
  • deploy/middleman → Middleman Kubernetes manifests

🧹 Cleaning Up

To tear everything down, run:

tilt down

This will also remove generated secrets and certs from disk:

  • deploy/postgres/dev/postgres-secrets.yml
  • deploy/postgres/dev/postgres-tls.yml
  • deploy/postgres/dev/certs/server.crt
  • deploy/postgres/dev/certs/server.key

📝 Notes

  • The postgres-middleman-connection secret is updated every time a new password is generated.
  • If you want to inspect logs or port-forwards outside of Tilt, run:
kubectl get pods
kubectl logs <pod-name>
kubectl port-forward <pod> 3000:3000

Happy hacking!

Clone this wiki locally