Skip to content

Getting Started

Jump to bottom
Eric Mann edited this page Mar 19, 2026 · 4 revisions

Getting Started with Displace

This guide walks you through the complete journey from a fresh system to a fully-functional WordPress site running on your local Kubernetes cluster. By the end, you'll have hands-on experience with the core Displace workflow.

What You'll Build

flowchart LR
    subgraph local["Your Local Machine"]
        cli["Displace CLI"]
        docker["Docker"]
    end

    subgraph cluster["Local k3d Cluster"]
        wp["WordPress"]
        db["MariaDB"]
        ingress["Ingress Controller"]
    end

    cli -->|"manages"| cluster
    docker -->|"runs"| cluster
    ingress -->|"exposes"| wp
    wp -->|"connects"| db
Loading

Time to complete: ~15 minutes

Step 1: Prerequisites

Before installing Displace, ensure your system meets these requirements.

System Requirements

Requirement Minimum Recommended
Operating System Linux or macOS Ubuntu 22.04+, macOS 13+
RAM 4 GB 8 GB or more
Disk Space 10 GB free 20 GB or more
CPU 2 cores 4 cores or more

Windows Users: Use WSL2 with Ubuntu. Native Windows is not supported.

Required Software

Displace will install most tools automatically, but you need:

Tool Purpose Check Command
Docker Container runtime docker --version
curl Download installer curl --version

Installing Docker

If Docker isn't installed:

Ubuntu/Debian:

curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
# Log out and back in for group changes to take effect

macOS: Download and install Docker Desktop for Mac.

Verify Docker is Running

docker version

Expected output:

Client:
 Version:           27.3.1
 API version:       1.47
 ...

Server:
 Engine:
  Version:          27.3.1
  ...

If you see "Cannot connect to the Docker daemon," start Docker Desktop or run sudo systemctl start docker.

Step 2: Install Displace CLI

One-Line Installation

Run this command in your terminal:

curl -sSL https://raw.githubusercontent.com/displacetech/displace-cli/main/install.sh | bash

Expected output:

Displace CLI Installer
=======================

Detecting system... Linux x86_64
Downloading displace v2.0.0...
Installing to /usr/local/bin/displace...
Installation complete!

Run 'displace install' to complete setup.

Alternative Installation Methods

Install to user directory (no sudo required):

curl -sSL https://raw.githubusercontent.com/displacetech/displace-cli/main/install.sh | bash -s -- --user

Install specific version:

curl -sSL https://raw.githubusercontent.com/displacetech/displace-cli/main/install.sh | bash -s -- --version v2.0.0

Verify Installation

displace version

Expected output:

Displace CLI
  Version:    2.0.0
  Build Date: 2026-01-07
  Go Version: go1.25.7
  Platform:   linux/amd64

Troubleshooting Installation

Problem Solution
"command not found" Add /usr/local/bin to your PATH or log out and back in
Permission denied Use --user flag or run with sudo
Download failed Check internet connection; try wget instead of curl

Step 3: Create Your Local Cluster

The displace install command sets up your complete local development environment.

Run Initial Setup

displace install

This command is interactive and will guide you through the setup process.

Expected output:

Displace Setup
==============

Checking system requirements...
  ✓ Docker 27.3.1 detected
  ✓ Sufficient disk space (45 GB available)
  ✓ Sufficient memory (16 GB available)

Installing development tools...
  ✓ kubectl v1.32.0
  ✓ helm v3.16.0
  ✓ k3d v5.8.0
  ✓ k9s v0.32.0

Creating local Kubernetes cluster...
  ✓ Created k3d cluster: displace-local
  ✓ Configured kubectl context

Installing cluster components...
  ✓ Ingress controller (nginx)
  ✓ Monitoring stack (Prometheus, Grafana, Alertmanager)
  ✓ Cloudflare Tunnel daemon

Downloading templates...
  ✓ wordpress
  ✓ static
  ✓ laravel
  ✓ simplephp

Setup complete! Your local cluster is ready.

Next steps:
  1. Create a project:  displace project init wordpress
  2. Deploy locally:    displace project deploy --cluster displace-local
  3. Check status:      displace status

What Gets Installed

flowchart TB
    subgraph tools["Development Tools"]
        kubectl["kubectl"]
        helm["Helm"]
        k3d["k3d"]
        k9s["k9s"]
    end

    subgraph cluster["Local k3d Cluster"]
        subgraph system["System Components"]
            nginx["Ingress Controller"]
            cf["Cloudflare Tunnel"]
        end
        subgraph monitoring["Monitoring Stack"]
            prom["Prometheus"]
            grafana["Grafana"]
            alert["Alertmanager"]
        end
    end

    tools --> cluster
Loading
Component Purpose
kubectl Kubernetes command-line tool
Helm Kubernetes package manager
k3d Lightweight Kubernetes for development
k9s Terminal-based Kubernetes UI
Ingress Controller Routes external traffic to services
Monitoring Stack Prometheus, Grafana, Alertmanager for observability
Cloudflare Tunnel Secure external access without exposing ports

Verify the Cluster

displace status

Expected output:

Displace System Status
======================

CLI Version: 2.0.0

Tools:
  ✓ docker      27.3.1
  ✓ kubectl     1.32.0
  ✓ helm        3.16.0
  ✓ k3d         5.8.0
  ✓ k9s         0.32.0

Local Cluster: displace-local
  Status:       Running
  Nodes:        1
  Pods:         12/12 Ready
  Context:      k3d-displace-local

Monitoring:
  Prometheus:   Running
  Grafana:      Running (admin/admin)
  Alertmanager: Running

Check the cluster directly:

displace cluster status displace-local

Expected output:

Cluster: displace-local
=======================

Provider:     local (k3d)
Status:       Running
K8s Version:  v1.31.2+k3s1

Nodes:
  NAME                          STATUS   ROLES                  AGE
  k3d-displace-local-server-0   Ready    control-plane,master   5m

System Pods:
  NAMESPACE      NAME                                      READY   STATUS
  kube-system    coredns-7c444764-xxxxx                   1/1     Running
  kube-system    local-path-provisioner-xxxxx             1/1     Running
  ingress-nginx  ingress-nginx-controller-xxxxx           1/1     Running
  monitoring     prometheus-server-xxxxx                   1/1     Running
  monitoring     grafana-xxxxx                             1/1     Running

Step 4: Initialize a WordPress Project

Now let's create your first WordPress site.

Create Project Directory

mkdir my-wordpress-site && cd my-wordpress-site

Initialize with WordPress Template

displace project init wordpress

The CLI will prompt you for configuration:

Displace Project Initialization
================================

Template: wordpress

Enter project name [my-wordpress-site]: my-wordpress-site
Enter Kubernetes namespace [my-wordpress-site]: my-wordpress-site
Enter domain name [wordpress.local]: my-site.local

Generating project files...
  ✓ Created manifests/01-namespace.yaml
  ✓ Created manifests/02-database-secret.yaml
  ✓ Created manifests/03-mariadb.yaml
  ✓ Created manifests/04-wordpress.yaml
  ✓ Created manifests/05-ingress.yaml
  ✓ Created .credentials
  ✓ Created .gitignore
  ✓ Created README.md

Project initialized successfully!

Your credentials have been saved to .credentials
  WordPress Admin: admin
  WordPress Password: <generated>
  Database Password: <generated>

Next: Run 'displace project deploy --cluster displace-local'

Understanding the Generated Files

my-wordpress-site/
├── README.md                    # Project documentation
├── .gitignore                   # Protects secrets from git
├── .credentials                 # Contains all passwords (git-ignored)
├── manifests/                   # Kubernetes configurations
│   ├── 01-namespace.yaml        # Isolated namespace for the project
│   ├── 02-database-secret.yaml  # Database credentials
│   ├── 03-mariadb.yaml          # MariaDB database deployment
│   ├── 04-wordpress.yaml        # WordPress application
│   └── 05-ingress.yaml          # External access configuration
└── secrets/                     # Secret overrides (git-ignored)
    └── database-secret-override.yaml

View Your Credentials

Your generated passwords are stored safely:

cat .credentials

Example output:

# WordPress Credentials
WORDPRESS_USERNAME=admin
WORDPRESS_PASSWORD=SecurePass123abc

# Database Credentials
MARIADB_ROOT_PASSWORD=RootPass456def
MARIADB_PASSWORD=DBPass789ghi

Security Note: The .credentials file is automatically added to .gitignore. Never commit passwords to version control.

Review Project Info

displace project info

Expected output:

Project: my-wordpress-site
==========================

Template:     wordpress
Namespace:    my-wordpress-site
Domain:       my-site.local
Status:       Not deployed

Components:
  - WordPress (custom build, WP 6.9.4 / PHP 8.3)
  - MariaDB (mariadb:11.5)

Manifests:
  ✓ manifests/01-namespace.yaml
  ✓ manifests/02-database-secret.yaml
  ✓ manifests/03-mariadb.yaml
  ✓ manifests/04-wordpress.yaml
  ✓ manifests/05-ingress.yaml

Step 5: Deploy to Your Local Cluster

Deploy the Project

displace project deploy --cluster displace-local

Expected output:

Deploying to cluster: displace-local
=====================================

Applying manifests...
  ✓ namespace/my-wordpress-site created
  ✓ secret/database-secret created
  ✓ persistentvolumeclaim/mariadb-pvc created
  ✓ deployment/mariadb created
  ✓ service/mariadb-service created
  ✓ persistentvolumeclaim/wordpress-pvc created
  ✓ deployment/wordpress created
  ✓ service/wordpress-service created
  ✓ ingress/wordpress-ingress created

Waiting for pods to be ready...
  ⏳ mariadb-xxxxxxxxxx-xxxxx: ContainerCreating
  ⏳ wordpress-xxxxxxxxxx-xxxxx: ContainerCreating

  ✓ mariadb-xxxxxxxxxx-xxxxx: Running (1/1)
  ✓ wordpress-xxxxxxxxxx-xxxxx: Running (1/1)

Deployment complete!

Access your site:
  Local URL: http://my-site.local.displace.tech
  Port Forward: displace project port-forward 8080:80

Watch Deployment Progress

In a separate terminal, watch the pods come up:

kubectl get pods -n my-wordpress-site -w

Expected output (updating in real-time):

NAME                         READY   STATUS              RESTARTS   AGE
mariadb-5d4c6b8f9-x2k4m      0/1     ContainerCreating   0          5s
wordpress-7f8d9e6c5-p3n7q    0/1     Init:0/1            0          5s
mariadb-5d4c6b8f9-x2k4m      1/1     Running             0          15s
wordpress-7f8d9e6c5-p3n7q    0/1     PodInitializing     0          20s
wordpress-7f8d9e6c5-p3n7q    1/1     Running             0          35s

Press Ctrl+C to stop watching.

Verify Deployment

displace project info

Expected output (after deployment):

Project: my-wordpress-site
==========================

Template:     wordpress
Namespace:    my-wordpress-site
Domain:       my-site.local
Cluster:      displace-local
Status:       Deployed ✓

Pods:
  NAME                         READY   STATUS    RESTARTS   AGE
  mariadb-5d4c6b8f9-x2k4m      1/1     Running   0          2m
  wordpress-7f8d9e6c5-p3n7q    1/1     Running   0          2m

Services:
  NAME                TYPE        CLUSTER-IP      PORT(S)
  mariadb-service     ClusterIP   10.43.xxx.xxx   3306/TCP
  wordpress-service   ClusterIP   10.43.xxx.xxx   80/TCP

Access:
  URL: http://my-site.local.displace.tech
  Port Forward: displace project port-forward 8080:80

Step 6: Access Your WordPress Site

Option A: Using the Local Domain (Recommended)

Displace configures automatic DNS for local development. Your site is available at:

http://my-site.local.displace.tech

Open this URL in your browser.

Option B: Using Port Forwarding

If the local domain doesn't work, use port forwarding:

displace project port-forward 8080:80

Expected output:

Forwarding from 127.0.0.1:8080 -> 80
Forwarding from [::1]:8080 -> 80

Keep this terminal open and visit: http://localhost:8080

Complete WordPress Setup

When you first access WordPress, you'll see the setup wizard:

flowchart LR
    A["Open Browser"] --> B["WordPress Welcome"]
    B --> C["Language Selection"]
    C --> D["Login with Credentials"]
    D --> E["WordPress Dashboard"]
Loading
  1. Select Language: Choose your preferred language
  2. Login: Use the credentials from your .credentials file:
    • Username: admin
    • Password: (from .credentials file)
  3. Dashboard: You're now in the WordPress admin panel

Verify Everything Works

  • Frontend: Visit http://my-site.local.displace.tech, or run displace project port-forward 8080:80 and visit http://localhost:8080
  • Admin Panel: Visit http://my-site.local.displace.tech/wp-admin/ (or http://localhost:8080/wp-admin/ after displace project port-forward 8080:80)
  • Check Logs: kubectl logs -n my-wordpress-site -l app.kubernetes.io/name=wordpress

Step 7: Next Steps

Congratulations! You've successfully deployed WordPress on Kubernetes. Here's where to go next:

Explore Your Deployment

# View all resources in your namespace
kubectl get all -n my-wordpress-site

# Check pod logs
kubectl logs -n my-wordpress-site deployment/wordpress

# Access a shell in the WordPress container
kubectl exec -it -n my-wordpress-site deployment/wordpress -- bash

# Access the database
kubectl exec -it -n my-wordpress-site deployment/mariadb -- mysql -u wordpress -p

Try Other Templates

# List available templates
displace template list

# Initialize a static site
mkdir my-static-site && cd my-static-site
displace project init static

# Initialize a Laravel app
mkdir my-laravel-app && cd my-laravel-app
displace project init laravel

Deploy to Production

Ready for production? Configure a cloud provider:

# Authenticate with Displace (required for cloud providers)
displace auth login

# Configure AWS
displace provider aws configure

# Create a production cluster
displace cluster create production --provider aws --region us-west-2

# Deploy your project to production
displace project deploy --cluster production

Learn More

Topic Documentation
Templates Application Templates
Local Development Local Providers
Cloud Deployment Cloud Providers
AWS Setup AWS Setup Guide
Cloudflare Tunnel Cloudflare Tunnel
Troubleshooting Troubleshooting Guide

Troubleshooting

Installation Issues

"displace: command not found"

# Check if installed
ls -la /usr/local/bin/displace

# Add to PATH if using --user install
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Docker not running

# Linux
sudo systemctl start docker

# macOS
# Open Docker Desktop application

Cluster Issues

Cluster won't start

# Check Docker status
docker info

# Delete and recreate cluster
displace cluster destroy displace-local
displace install

Pods stuck in Pending state

# Check for resource issues
kubectl describe pod -n my-wordpress-site <pod-name>

# Check node resources
kubectl describe node

Deployment Issues

Pod in CrashLoopBackOff

# Check pod logs
kubectl logs -n my-wordpress-site <pod-name>

# Check pod events
kubectl describe pod -n my-wordpress-site <pod-name>

Can't access the site

# Verify pods are running
kubectl get pods -n my-wordpress-site

# Check service exists
kubectl get svc -n my-wordpress-site

# Test port forward
displace project port-forward 8080:80

Database connection errors

# Check MariaDB pod
kubectl logs -n my-wordpress-site deployment/mariadb

# Verify secret exists
kubectl get secret -n my-wordpress-site database-secret

# Test database connection from WordPress pod
kubectl exec -it -n my-wordpress-site deployment/wordpress -- nc -zv mariadb-service 3306

Getting Help

# Show command help
displace --help
displace project --help

# Enable verbose output
displace project deploy --cluster displace-local --verbose

# Check system status
displace status

Need more help?

Clean Up

When you're done experimenting, clean up your resources:

# Remove the WordPress deployment
displace project destroy displace-local

# Or remove just the namespace
kubectl delete namespace my-wordpress-site

# To remove everything (cluster and tools)
displace uninstall

You've completed the Getting Started guide!

You now know how to:

  • Install and configure Displace CLI
  • Create a local Kubernetes cluster
  • Initialize and deploy WordPress
  • Access and manage your deployment
  • Troubleshoot common issues

Next: Explore Application Templates to see what else you can deploy, or read about Cloud Providers to deploy to production.

Home

Getting Started

Providers

Templates

Development

Guides

Infrastructure

Reference

Clone this wiki locally