Skip to content

Quick Start

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

Quick Start Guide

Get up and running with the Displace CLI in minutes. This guide will walk you through installation, initial setup, and your first deployment.

Installation

Prerequisites

  • Operating System: Linux or macOS (Windows users should use WSL2)
  • Internet Connection: Required for downloading tools and templates
  • Basic Requirements: curl, jq, and tar (usually pre-installed)

One-Line Installation (Recommended)

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

Alternative Installation Methods

Download and run manually:

wget https://raw.githubusercontent.com/displacetech/displace-cli/main/install.sh
chmod +x install.sh
./install.sh

Install specific version:

./install.sh --version v2.0.0

Install to user directory (no sudo required):

./install.sh --user

Verify Installation

# Check version and build info
displace version

# Check system status
displace status

Updates

Displace automatically checks for updates every hour. You can also manage updates manually:

# Check for available updates
displace update --check-only

# Install available updates
displace update

# View current update settings
displace update --configure

# Enable/disable automatic update checking
displace update --enable-auto
displace update --disable-auto

Initial Setup

After installation, run the setup command to configure your local environment:

displace install

This will:

  1. Create the ~/.displace configuration directory
  2. Install required development tools (Docker, kubectl, Helm, etc.)
  3. Set up a local k3d Kubernetes cluster
  4. Install monitoring stack (Prometheus, Grafana, Alertmanager)
  5. Install Cloudflare Tunnel for secure ingress
  6. Download initial templates

Your First Project

1. Initialize a Project

Create a new project using a template:

# Create project directory
mkdir my-wordpress-site && cd my-wordpress-site

# Initialize with WordPress template
displace project init wordpress

This creates a complete WordPress deployment with:

  • WordPress application
  • MariaDB database
  • Ingress configuration
  • Persistent storage
  • Security configurations

2. Deploy Locally

Deploy your project to the local development cluster:

# Deploy to local k3d cluster (always free)
displace project deploy --cluster displace-local

3. Access Your Application

# Get project information and URLs
displace project info

# Access via ingress (automatic)
echo "Visit http://my-wordpress-site.local.displace.tech"

# Or port forward for direct access if needed
kubectl port-forward service/my-wordpress-site-wordpress 8080:80

Visit http://my-wordpress-site.local.displace.tech to see your WordPress site.

4. Monitor Your Deployment

Access the built-in monitoring stack:

# Open Grafana dashboard
kubectl port-forward -n monitoring svc/grafana 3000:80

Visit http://grafana.local.displace.tech:3000 (admin/admin) to view metrics and logs.

Authentication (Optional for Community Local Use)

For cloud deployments and advanced features, authenticate with your Displace account:

# Login with your API key
displace auth login

# Check subscription status and tier
displace auth status

Subscription Tier Features

Feature Community (Free) Starter ($29/mo per cluster) Professional ($79/mo per cluster) Founder ($499/mo flat)
Local Development ✅ Full ✅ Full ✅ Full ✅ Full
Cloud providers ❌ No ✅ Limited* ✅ Multiple ✅ Unlimited
Templates ✅ All ✅ All ✅ All ✅ All
Team Features ❌ No ❌ No ✅ Yes ✅ Yes
Support Community Community Email/Chat Priority

* Starter is locked to the first cloud provider you use.

Visit displace.tech to create an account and choose your subscription tier.

Cloud Provider Setup (Requires Subscription)

AWS Example (Starter+ Required)

# Authenticate with Displace first
displace auth login

# Configure AWS provider (requires paid subscription)
displace provider aws configure
# Follow prompts for region and AWS profile

# Create production cluster
displace cluster create production --provider aws

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

Available Templates

List all available project templates:

displace template list

Common templates include:

  • wordpress - Complete WordPress site with database
  • laravel - PHP Laravel application framework
  • simplephp - Lightweight PHP without frameworks
  • static - High-performance static site hosting

Common Commands

Project Management

displace project init <template>     # Initialize new project
displace project deploy              # Deploy to cluster
displace project status              # Show deployment status
displace project status --watch      # Live-updating status display
displace project info                # Show project details
displace project restart             # Rolling restart of pods
displace project logs                # View application logs
displace project shell               # Shell into running pod
displace project port-forward        # Forward local port to service
displace project destroy             # Remove deployment

Cluster Management

displace cluster create <name>      # Create new cluster
displace cluster list               # List all clusters
displace cluster status <name>      # Check cluster health
displace cluster bootstrap <name>   # Install components on existing cluster
displace cluster scale <name> <n>   # Scale to n worker nodes
displace cluster kubeconfig <name>  # Configure kubectl access
displace cluster import             # Import existing kubeconfig clusters
displace cluster import --all       # Import all clusters without prompting
displace cluster delete <name>      # Delete a cluster

Provider Management

displace provider list              # List configured providers
displace provider aws configure     # Configure AWS provider
displace provider test aws          # Test provider connectivity

Monitoring

kubectl port-forward -n monitoring svc/grafana 3000:80  # Access Grafana
kubectl get pods                    # Check pod status
kubectl logs <pod-name>             # View application logs

System Management

displace status                     # Show system status
displace version                    # Show version info
displace update                     # Update to latest version
displace update --check-only        # Check for updates only
displace uninstall                  # Remove Displace and dependencies

Template Management

displace template list              # List available templates
displace template info <name>       # Show template details and variables

Provider Subcommands (AWS Example)

displace provider aws configure     # Set up AWS credentials
displace provider aws audit         # Validate AWS configuration
displace provider aws edit          # Edit AWS settings
displace provider aws policy        # Show required IAM policy

New Command Reference

Project Restart

Perform a rolling restart of application pods without redeploying:

# Restart pods in current project
displace project restart

# Restart specific deployment
displace project restart --deployment wordpress

# Restart all deployments in namespace
displace project restart --all

# Target specific cluster
displace project restart --cluster production

Use cases:

  • Pick up ConfigMap or Secret changes
  • Force pod recreation without image changes
  • Clear application caches
  • Recover from transient issues

Expected output:

🔄 Restarting deployment wordpress in namespace my-site...
✅ Restart initiated successfully

💡 Monitor progress with:
   displace project logs -f
   kubectl rollout status deployment/wordpress -n my-site

Cluster Bootstrap

Install core components (monitoring, ingress, Cloudflare Tunnel) on an existing cluster:

# Bootstrap with all components (default)
displace cluster bootstrap production --provider aws

# Bootstrap specific cluster
displace cluster bootstrap my-cluster --provider gcp

# Disable specific components
displace cluster bootstrap production --provider aws --monitoring=false

# Wait for cluster to be ready before bootstrapping (AWS)
displace cluster bootstrap production --provider aws --wait

Flags:

Flag Default Description
--provider Provider name (required)
--monitoring true Install Prometheus, Grafana, Alertmanager
--ingress true Install nginx ingress controller
--cloudflared true Install Cloudflare Tunnel daemon
--wait false Wait for cluster ready before bootstrapping

Expected output:

Bootstrapping cluster: production (aws)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

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

Verifying installation...
  ✓ ingress-nginx-controller: Running
  ✓ prometheus-server: Running
  ✓ grafana: Running
  ✓ cloudflared: Running

Bootstrap complete!

Access monitoring:
  kubectl port-forward -n monitoring svc/grafana 3000:80

Use cases:

  • Setting up imported clusters
  • Re-installing components after updates
  • Configuring clusters created outside Displace
  • Selective component installation

Note: displace cluster create automatically runs bootstrap. Use this command for existing clusters or when you need to reinstall components.

Cluster Scale

Scale the number of worker nodes in a cluster:

# Scale cluster to 3 nodes
displace cluster scale production 3

# Scale with explicit provider
displace cluster scale production 5 --provider aws

Arguments:

  • cluster-name - Name of the cluster to scale
  • node-count - Target number of worker nodes (minimum: 1)

Behavior by provider:

  • AWS/GCP/DigitalOcean: Updates node group/pool via infrastructure tooling
  • Local k3d: Adds or removes agent containers

Expected output:

Scaling cluster 'production' (aws)
  Current nodes: 2
  Target nodes:  5

Scaling in progress...

Automatic Docker Build (Deploy)

When deploying a project with a Dockerfile, Displace automatically builds and pushes images:

# Automatic build + deploy (if Dockerfile exists)
displace project deploy --cluster displace-local

# Skip automatic build
displace project deploy --skip-build

# Build only (no deploy)
displace project deploy --build-only

# Custom image tag
displace project deploy --tag v1.2.3

# Build but don't push
displace project deploy --no-push

Workflow:

  1. Detects Dockerfile in project root
  2. Builds image with Docker
  3. Pushes to cluster registry (local k3d registry)
  4. Updates manifest image references
  5. Deploys to cluster

Project Status (Live Watch)

Monitor your deployment in real-time with live-updating status display:

# Show current status (single snapshot)
displace project status

# Watch with live updates (default: 2-second refresh)
displace project status --watch

# Custom refresh interval (5 seconds)
displace project status --watch --interval 5

# Watch specific cluster
displace project status --watch --cluster production

Flags:

Flag Short Default Description
--watch -w false Enable live-updating display
--interval 2 Refresh interval in seconds
--cluster Target specific cluster

Expected output (watch mode):

📊 Project Status: my-wordpress-site                    [Live]
═══════════════════════════════════════════════════════════════
Namespace: my-wordpress-site
Context:   k3d-displace-local
Updated:   2026-01-07 14:32:05 (every 2s)

PODS
────────────────────────────────────────────────────────────────
NAME                              READY   STATUS    RESTARTS   AGE
✅ wordpress-7d9f8b6c4d-x2k9m     1/1     Running   0          2h
✅ mariadb-5c8f7b9d6e-p4j2n       1/1     Running   0          2h

SERVICES
────────────────────────────────────────────────────────────────
NAME        TYPE        CLUSTER-IP      PORTS
wordpress   ClusterIP   10.43.128.45    80/TCP
mariadb     ClusterIP   10.43.192.12    3306/TCP

RECENT EVENTS
────────────────────────────────────────────────────────────────
AGE    TYPE     REASON              MESSAGE
2m     ✅       Scheduled           Successfully assigned...
2m     ✅       Pulled              Container image already...
2m     ✅       Created             Created container wordpress
2m     ✅       Started             Started container wordpress

Press Ctrl+C to exit watch mode

Status indicators:

Icon Meaning
✅ Running/healthy
🔄 Starting/creating
⏳ Pending
🛑 Terminating
❌ Error/CrashLoop
⚠️ Warning event

Use cases:

  • Live demos and presentations
  • Monitoring deployment rollouts
  • Debugging pod startup issues
  • Watching for crash loops or restarts

Project Logs

View and stream logs from your deployed application:

# View recent logs
displace project logs

# Stream logs in real-time
displace project logs --follow

# Show last 100 lines
displace project logs --tail 100

# View logs from specific container
displace project logs --container php-fpm

# View logs from previous container instance
displace project logs --previous

# Show logs from last hour
displace project logs --since 1h

# Include timestamps
displace project logs --timestamps

# View logs from all pods
displace project logs --all

Flags:

Flag Short Description
--follow -f Stream logs in real-time
--tail Number of lines from end (0 = all)
--container -c Target specific container
--cluster Target cluster (auto-detected)
--all View logs from all pods
--previous -p Logs from previous container instance
--since Show logs since duration (1h, 30m, 5s)
--timestamps Include timestamps in output

Expected output:

Streaming logs from: my-wordpress-site/wordpress-7d9f8b6c4d-x2k9m

[php-fpm] 172.17.0.1 - - [07/Jan/2026:14:32:05 +0000] "GET / HTTP/1.1" 200 4523
[php-fpm] 172.17.0.1 - - [07/Jan/2026:14:32:06 +0000] "GET /wp-admin/ HTTP/1.1" 302 0
[nginx] 2026/01/07 14:32:07 [notice] upstream response time: 0.045s

Project Shell

Open an interactive shell in a running application container:

# Open shell (tries bash, falls back to sh)
displace project shell

# Shell into specific container
displace project shell --container nginx

# Run a single command
displace project shell --command "ls -la /var/www/html"

# Target specific cluster
displace project shell --cluster production

Flags:

Flag Short Description
--container -c Target specific container
--cluster Target cluster (auto-detected)
--command Run command instead of interactive shell

Expected output:

Connecting to: my-wordpress-site/wordpress-7d9f8b6c4d-x2k9m

root@wordpress-7d9f8b6c4d-x2k9m:/var/www/html#

Use cases:

  • Debugging application issues
  • Running one-off commands (migrations, cache clear)
  • Inspecting file system
  • Testing network connectivity

Project Port-Forward

Forward a local port to your deployed application service:

# Auto-detect service and port
displace project port-forward

# Specify port mapping (local:remote)
displace project port-forward 8080:80

# Forward to specific service
displace project port-forward --service wordpress

# Bind to all interfaces (network accessible)
displace project port-forward --address 0.0.0.0

# Custom local port only
displace project port-forward --local-port 3000

Flags:

Flag Short Description
--local-port -l Local port (default: same as remote)
--remote-port -r Remote service port (auto-detected)
--cluster Target cluster (auto-detected)
--service -s Service name (auto-detected)
--address Bind address (default: localhost)

Expected output:

Port forwarding: localhost:8080 → wordpress-service:80

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

Press Ctrl+C to stop

Use cases:

  • Local development and testing
  • Accessing services without ingress
  • Database connections (MySQL, PostgreSQL)
  • Admin interfaces not exposed publicly

Uninstall

Remove Displace CLI and optionally its installed dependencies:

# Uninstall Displace CLI
displace uninstall

# Uninstall with all installed tools
displace uninstall --all

# Preview what would be removed
displace uninstall --dry-run

Flags:

Flag Description
--all Also remove installed tools (kubectl, helm, k3d, etc.)
--dry-run Show what would be removed without removing
--keep-config Keep ~/.displace configuration directory

Expected output:

Displace Uninstaller
====================

The following will be removed:
  ✓ Displace CLI binary (/usr/local/bin/displace)
  ✓ Configuration directory (~/.displace)

Installed tools will be kept:
  - kubectl, helm, k3d, k9s, terraform

Proceed with uninstall? (y/N): y

Removing Displace CLI...
  ✓ Removed /usr/local/bin/displace
  ✓ Removed ~/.displace

Uninstall complete.

Note: Local k3d clusters are still running.
To remove: k3d cluster delete displace-local

Template Info

Show detailed information about a template including variables and configuration:

# Show WordPress template details
displace template info wordpress

# Show Laravel template details
displace template info laravel

Expected output:

Template: wordpress
===================

Description: Production-ready WordPress deployment with MariaDB

Version:     27.0.0
Source:      github.com/DisplaceTech/displace-template-wordpress
Tier:        Community (Free)

Components:
  - WordPress 6.9.4 (PHP 8.3)
  - MariaDB 11.5
  - Nginx Ingress
  - Persistent Storage

Variables:
  NAME                   DEFAULT        DESCRIPTION
  ─────────────────────────────────────────────────────────
  ProjectName            (required)     Project identifier
  Namespace              (from project) Kubernetes namespace
  Domain                 (required)     Application domain
  PHPVersion             8.3            PHP version
  WordPressVersion       6.9.4          WordPress version
  WordPressReplicas      1              Number of pods
  WordPressStorageSize   10Gi           Uploads PVC size
  MariaDBStorageSize     8Gi            Database PVC size
  MemoryLimit            512Mi          Container memory limit
  CPULimit               500m           Container CPU limit

Usage:
  mkdir my-site && cd my-site
  displace project init wordpress

Provider AWS Subcommands

Manage AWS provider configuration and credentials:

displace provider aws configure

Set up AWS credentials and region:

displace provider aws configure

Expected output:

AWS Provider Configuration
==========================

Enter AWS region [us-west-2]: us-west-2
Enter AWS profile [default]: default

Validating credentials...
  ✓ AWS credentials valid
  ✓ Account ID: 123456789012
  ✓ IAM User: deploy-user

Checking permissions...
  ✓ EKS: Full access
  ✓ EC2: Full access
  ✓ IAM: Limited access (sufficient)

AWS provider configured successfully!

Next: Create a cluster with:
  displace cluster create production --provider aws

displace provider aws audit

Display current configuration and validate credentials:

displace provider aws audit

Expected output:

AWS Provider Audit
==================

Configuration:
  Region:      us-west-2
  Profile:     default
  Config File: ~/.displace/providers/aws/credentials

Credentials:
  Status:      ✓ Valid
  Account ID:  123456789012
  User ARN:    arn:aws:iam::123456789012:user/deploy-user
  Expires:     Never (IAM user)

Permissions Check:
  ✓ eks:CreateCluster
  ✓ eks:DeleteCluster
  ✓ eks:DescribeCluster
  ✓ eks:ListClusters
  ✓ ec2:CreateVpc
  ✓ ec2:CreateSubnet
  ✓ iam:CreateRole
  ⚠ iam:CreatePolicy (limited - may need manual policy)

Existing Resources:
  Clusters:    2 (production, staging)
  VPCs:        1 (displace-vpc)

All checks passed!

displace provider aws edit

Edit AWS configuration settings:

displace provider aws edit

Opens configuration in your default editor or prompts for changes:

AWS Provider Edit
=================

Current configuration:
  Region:  us-west-2
  Profile: default

Enter new region [us-west-2]: us-east-1
Enter new profile [default]: production

Configuration updated!
Run 'displace provider aws audit' to verify.

displace provider aws policy

Show the required IAM policy for EKS management:

displace provider aws policy

Expected output:

Required IAM Policy for Displace
================================

Attach this policy to your IAM user or role:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "eks:*",
        "ec2:CreateVpc",
        "ec2:DeleteVpc",
        "ec2:CreateSubnet",
        "ec2:DeleteSubnet",
        "ec2:CreateSecurityGroup",
        "ec2:DeleteSecurityGroup",
        "ec2:AuthorizeSecurityGroupIngress",
        "ec2:AuthorizeSecurityGroupEgress",
        "ec2:CreateInternetGateway",
        "ec2:AttachInternetGateway",
        "ec2:CreateRouteTable",
        "ec2:CreateRoute",
        "ec2:AssociateRouteTable",
        "ec2:AllocateAddress",
        "ec2:CreateNatGateway",
        "ec2:DescribeVpcs",
        "ec2:DescribeSubnets",
        "ec2:DescribeSecurityGroups",
        "ec2:DescribeRouteTables",
        "ec2:DescribeInternetGateways",
        "ec2:DescribeNatGateways",
        "ec2:DescribeAddresses",
        "ec2:CreateTags"
      ],
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "iam:CreateRole",
        "iam:DeleteRole",
        "iam:AttachRolePolicy",
        "iam:DetachRolePolicy",
        "iam:GetRole",
        "iam:PassRole",
        "iam:CreateServiceLinkedRole"
      ],
      "Resource": "*"
    }
  ]
}

Copy this policy and create it in the AWS IAM Console:
  1. Go to IAM → Policies → Create Policy
  2. Select JSON tab and paste the above
  3. Name it "DisplaceEKSManagement"
  4. Attach to your user/role

Next Steps

Now that you have Displace running locally:

  1. Explore Templates: Try different project templates to understand capabilities
  2. Learn Providers: Read about Local Providers and Cloud Providers
  3. Customize Applications: Modify the generated Kubernetes manifests for your needs
  4. Set Up Monitoring: Explore Grafana dashboards for observability
  5. Deploy to Production: Configure cloud providers for production deployments

Troubleshooting

Common Issues

Installation fails:

  • Ensure you have internet connectivity
  • Check that curl, jq, and tar are installed
  • Try manual installation or user directory installation

Local cluster not starting:

  • Ensure Docker is running: docker version
  • Check cluster status: displace cluster status displace-local
  • Restart cluster: k3d cluster restart displace-local

Project deployment fails:

  • Check cluster status first
  • Verify project configuration: displace project info
  • Check pod logs: kubectl get pods and kubectl logs <pod-name>

Getting Help

# Show command help
displace <command> --help

# Check system status
displace status

# Enable verbose output
displace <command> --verbose

Community Support:

Next: Learn about Local Providers for development or Cloud Providers for production deployments.

Home

Getting Started

Providers

Templates

Development

Guides

Infrastructure

Reference

Clone this wiki locally