Installation¶

Install Playpen on Windows (WSL2) or macOS.

Prerequisites¶

Required software¶

Software	Version	Purpose
Kubernetes	Any	Container orchestration (via Docker Desktop, kind, or minikube)
kubectl	v1.28+	Kubernetes command-line tool
Docker	Latest	Container runtime and base image building
Helm	v3.12+	Package manager for Kubernetes

System requirements¶

Minimum - CPU: 4 cores - Memory: 8GB RAM - Disk: 50GB free - OS: Windows 10+ (WSL2) or macOS 10.15+

Recommended - CPU: 8 cores - Memory: 16GB RAM - Disk: 100GB free

Verify prerequisites¶

Linux/macOS:

./scripts/check-prerequisites.sh

Windows (PowerShell):

.\scripts\check-prerequisites.ps1

Quick installation¶

Install Playpen with a single command:

./scripts/setup.sh

This script: 1. Checks prerequisites 2. Installs Kubernetes foundation (namespaces, storage, RBAC) 3. Installs all platform services (PostgreSQL, Nexus, Dex, Jenkins) 4. Builds base images 5. Provides configuration instructions

Step-by-step installation¶

Step 1: Install Kubernetes foundation¶

Create namespaces, storage classes, and RBAC:

make install-k8s-foundation
# Or: ./scripts/install-k8s-foundation.sh

This creates: - Namespaces: playpen-platform (services) and playpen-apps (applications) - Storage Class: local-path for persistent volumes - RBAC: Service accounts and role bindings for Jenkins agents

Verify:

kubectl get namespaces | grep playpen
kubectl get storageclass local-path

Step 2: Install core services¶

Install platform services in order:

PostgreSQL¶

make install-postgres
# Or: ./scripts/install-postgres.sh

PostgreSQL provides the application database: - Storage: 10Gi persistent volume - Port: 5432 (ClusterIP service) - Credentials: Stored in Kubernetes secret postgres-credentials

Wait for readiness:

kubectl wait --for=condition=ready pod -l app=postgres -n playpen-platform --timeout=300s

Nexus Repository Manager¶

make install-nexus
# Or: ./scripts/install-nexus.sh

Nexus manages Maven artifacts and Docker images: - Storage: 20Gi persistent volume - Port: 8081 (ClusterIP service) - Initialization: Takes 5-10 minutes on first start

Wait for readiness:

kubectl wait --for=condition=ready pod -l app=nexus -n playpen-platform --timeout=600s

Dex OIDC Provider¶

make install-dex
# Or: ./scripts/install-dex.sh

Dex provides OIDC authentication: - Port: 5556 (ClusterIP service) - Storage: In-memory (stateless) - Configuration: Stored in ConfigMap

Wait for readiness:

kubectl wait --for=condition=ready pod -l app=dex -n playpen-platform --timeout=120s

Step 3: Install Jenkins¶

Note: Helm is required for Jenkins installation.

make install-jenkins
# Or: ./scripts/install-jenkins.sh

Jenkins provides CI/CD capabilities: - Storage: 20Gi persistent volume for job history - Port: 8080 (ClusterIP service) - Agents: Kubernetes ephemeral pods (Kaniko, Maven, Python)

Wait for readiness:

kubectl wait --for=condition=ready pod -l app.kubernetes.io/component=jenkins-controller -n playpen-platform --timeout=600s

Step 4: Build base images¶

Build the pre-configured base images:

make install-base-images
# Or: ./scripts/install-base-images.sh

This builds: - playpen/python-base: Python 3.11 with web frameworks and data science libraries - playpen/r-base: R environment with Posit compatibility - playpen/ml-runtime: ML runtime with PyTorch, transformers, and vector databases

Note: The ML runtime image is large (~3-4GB) and may take 10-15 minutes to build.

Verify images:

docker images | grep playpen

Step 5: Configure services¶

Configure services for first-time use:

make configure
# Or: ./scripts/configure-services.sh

This interactive script guides you through: 1. Nexus configuration (repositories, Docker registry, API tokens) 2. Jenkins configuration (Kubernetes cloud, credentials, agent templates) 3. Dex verification (OIDC endpoints, token issuance) 4. PostgreSQL setup (databases, users, permissions)

Platform-specific instructions¶

Windows (WSL2)¶

Enable WSL2
```
wsl --install
```
Install Docker Desktop
Download from docker.com
Enable WSL2 integration in Docker Desktop settings
Enable Kubernetes in Docker Desktop settings

Verify setup

# In WSL2 terminal
docker ps
kubectl cluster-info

Storage considerations
Uses local-path-provisioner for persistent volumes
Volumes are stored in WSL2 filesystem
Ensure sufficient disk space in WSL2

macOS¶

Install Docker Desktop
Download from docker.com
Enable Kubernetes in Docker Desktop settings

Alternative: Use kind or minikube

# Using kind
brew install kind
kind create cluster

# Using minikube
brew install minikube
minikube start

Storage considerations
Uses local-path-provisioner or hostPath storage
Ensure sufficient disk space

Verification¶

After installation, verify everything is working:

make verify
# Or: ./scripts/verify.sh

This checks: - All pods are running - Services are accessible - Storage is configured - RBAC is set up correctly

Manual verification¶

Check pod status:

kubectl get pods -n playpen-platform

All pods should be in Running state.

Check services:

kubectl get svc -n playpen-platform

Check storage:

kubectl get pvc -n playpen-platform

All PVCs should be Bound.

Post-installation configuration¶

Access services locally¶

Set up port forwarding:

make setup-port-forwards
# Or: ./scripts/setup-port-forwards.sh

This creates port forwards for: - Jenkins: http://localhost:8080 - Nexus: http://localhost:8081 - Dex: http://localhost:5556 - PostgreSQL: localhost:5432

Get service credentials¶

Jenkins admin password:

kubectl exec -n playpen-platform jenkins-0 -- \
  cat /var/jenkins_home/secrets/initialAdminPassword

Nexus admin password:

kubectl exec -n playpen-platform deployment/nexus -- \
  cat /nexus-data/admin.password

Dex client credentials:

# Client ID
kubectl get secret dex-credentials -n playpen-platform \
  -o jsonpath='{.data.client-id}' | base64 -d

# Client Secret
kubectl get secret dex-credentials -n playpen-platform \
  -o jsonpath='{.data.client-secret}' | base64 -d

PostgreSQL credentials:

# Username
kubectl get secret postgres-credentials -n playpen-platform \
  -o jsonpath='{.data.username}' | base64 -d

# Password
kubectl get secret postgres-credentials -n playpen-platform \
  -o jsonpath='{.data.password}' | base64 -d

Initial service setup¶

Jenkins: Log in with admin password, install suggested plugins, create admin user
Nexus: Log in with admin password, change password, create repositories
Dex: Verify OIDC endpoints are accessible
PostgreSQL: Create application databases as needed

Uninstallation¶

To completely remove Playpen:

make teardown
# Or: ./scripts/teardown.sh

Warning

This deletes all Kubernetes resources, persistent volumes, namespaces, and storage classes. Data will be permanently lost.

Manual uninstallation¶

# Delete Helm releases
helm uninstall jenkins -n playpen-platform

# Delete deployments
kubectl delete -f infra/postgres/postgres-deployment.yaml
kubectl delete -f infra/nexus/nexus-deployment.yaml
kubectl delete -f infra/dex/dex-deployment.yaml

# Delete namespaces (cascades to all resources)
kubectl delete namespace playpen-platform
kubectl delete namespace playpen-apps

# Delete storage classes
kubectl delete storageclass local-path

Troubleshooting¶

See Troubleshooting Guide for common installation issues.

Common issues: - Storage class not found: Install local-path-provisioner - Pods stuck in Pending: Check resource availability - Services not accessible: Verify port forwarding

Next steps¶

After successful installation:

Deploy your first workload
Explore platform guides
Review best practices