Skip to main content

Local Development Setup

In this tutorial, we will set up the tupynambalucas.dev monorepo on your local machine. By the end of this lesson, you will have the complete development environment running and ready for you to build features.

Prerequisites​

Before we begin, ensure you have the following installed:

  • Node.js version 22
  • PNPM version 11
  • Podman Desktop + Podman CLI + Compose Extension (instead of Docker)
  • Minikube and kubectl (for Kubernetes cluster mode)
  • Skaffold (for Kubernetes deployment pipelines and hot-reloading)
  • Git

Step 1: Clone the Repository​

First, clone the repository to your local workspace and navigate into it.

git clone https://github.com/tupynambalucas-dev/%GITHUB_REPO%.git
cd workspace

You should see a directory structure containing folders like docs, hub, cortex, renderer, studio, platform, and tools.

Step 2: Install Dependencies​

Next, install the project dependencies. Since this is a monorepo, we use PNPM to install everything at once.

Run the following command:

pnpm install

When it finishes, you will see output confirming dependencies are linked to the content-addressable store.

Step 3: Configure Environment Variables​

Each workspace manages its own local configuration. Copy the template .env.example files to create the active environment files:

# Set up Infrastructure environment variables
cp infrastructure/.env.example infrastructure/.env

# Set up Hub environment variables
cp hub/.env.example hub/.env
Open and Edit Configuration

Open the newly created .env files and add any required tokens (e.g., CLOUDFLARE_TUNNEL_TOKEN_HUB, CLOUDFLARE_TUNNEL_TOKEN_CORPORATE) to access cloud services.

Step 4: Configure Podman Machine​

Before starting any container workloads, initialize and start the default Podman machine (which will be used by Minikube):

podman machine init
podman machine start

Verify that the container engine is active:

podman info

Step 5: Start the Infrastructure​

To build all containers and deploy the full stack to your local Minikube cluster:

pnpm minikube:up
pnpm infra:dev

This command will:

  1. Start the Minikube cluster.
  2. Trigger Skaffold to build all required images.
  3. Hydrate Kustomize manifests.
  4. Deploy the Platform, Cortex, and Studio layers.
  5. Stream logs and hot-reload code changes automatically.

Step 6: Verify Access​

Once the services are running, verify access via the Cloudflare edge routes (or localhost if running offline):

  • Grafana: https://grafana-dev.tupynambalucas.dev
  • AgentGateway: https://agentgateway-mcp-dev.tupynambalucas.dev
  • Penpot: https://penpot-dev.tupynambalucas.dev

Next Steps​

For in-depth details on configuring Minikube network tunnels, Skaffold port forwarding, and environment variable resolution, see the Local Development Setup Guide.

Conclusion​

Congratulations! You have successfully cloned the repository, configured environment variables, started Minikube, and launched the local Kubernetes infrastructure. You are now fully equipped to start building and contributing to the project.