Configuration

Project Configuration

Displace uses a layered configuration system with global user settings, project-specific configuration, and environment variables. This guide covers all configuration options and file locations.

Configuration Hierarchy

flowchart TB
    subgraph layers["Configuration Layers"]
        env["Environment Variables<br/>(highest priority)"]
        project["Project Config<br/>(.displace/project.json)"]
        credentials["Project Credentials<br/>(.credentials)"]
        user["User Config<br/>(~/.displace/config.json)"]
        defaults["Built-in Defaults<br/>(lowest priority)"]
    end

    env --> project
    project --> credentials
    credentials --> user
    user --> defaults

Priority (highest to lowest):

Environment variables
Project configuration (.displace/project.json)
Project credentials (.credentials)
User configuration (~/.displace/config.json)
Built-in defaults

Global User Configuration

User-level configuration is stored in ~/.displace/ and applies to all projects.

Directory Structure

~/.displace/
├── config.json              # User settings and provider configs
├── auth.json                # API key (encrypted)
├── entitlements.json        # Cached subscription data
├── update_config.json       # Auto-update preferences
├── update_state.json        # Update check state
├── providers/               # Provider-specific credentials
│   ├── aws/
│   │   └── credentials
│   ├── gcp/
│   │   └── service-account.json
│   └── digitalocean/
│       └── token
├── clusters/                # Cluster state files
│   ├── displace-local/
│   └── production/
└── templates/               # Cached templates
    ├── wordpress/
    ├── laravel/
    └── static/

config.json

The main user configuration file:

{
  "aws": {
    "profile": "default",
    "region": "us-west-2"
  },
  "gcp": {
    "project": "my-project-123",
    "region": "us-central1",
    "zone": "us-central1-a",
    "credentialsFile": "~/.displace/providers/gcp/service-account.json"
  },
  "digitalocean": {
    "region": "nyc1",
    "tokenFile": "~/.displace/providers/digitalocean/token"
  },
  "clusters": [
    {
      "name": "displace-local",
      "provider": "local",
      "region": "",
      "status": "running",
      "version": "v1.31.2+k3s1",
      "nodeCount": 1,
      "createdAt": "2026-01-05T10:30:00Z",
      "updatedAt": "2026-01-07T10:30:00Z"
    },
    {
      "name": "production",
      "provider": "aws",
      "region": "us-west-2",
      "status": "running",
      "version": "1.32",
      "nodeCount": 3,
      "nodeType": "t3.medium",
      "createdAt": "2026-01-01T14:00:00Z",
      "updatedAt": "2026-01-07T08:00:00Z"
    }
  ]
}

Configuring Providers

# AWS
displace provider aws configure --region us-west-2 --profile default

# GCP
displace provider gcp configure --project my-project --region us-central1

# DigitalOcean
displace provider digitalocean configure --region nyc1

Project Configuration

Each Displace project has its own configuration in the .displace/ directory.

Project Directory Structure

my-project/
├── .displace/               # Displace project metadata
│   └── project.json         # Project configuration
├── .credentials             # Sensitive values (git-ignored)
├── .gitignore               # Includes .credentials, .displace/
├── manifests/               # Kubernetes manifests
├── Dockerfile               # Container build (if applicable)
├── Makefile                 # Build and deploy commands
└── README.md                # Project documentation

project.json

The project configuration file (.displace/project.json):

{
  "name": "my-wordpress-site",
  "description": "My WordPress blog",
  "template": "wordpress",
  "version": "1.0.0",
  "createdAt": "2026-01-05T10:30:00Z",
  "updatedAt": "2026-01-07T14:00:00Z",
  "templateInfo": {
    "name": "wordpress",
    "version": "27.0.0",
    "description": "Production-ready WordPress deployment",
    "source": "github.com/DisplaceTech/displace-template-wordpress"
  },
  "deployments": {
    "displace-local": {
      "clusterName": "displace-local",
      "provider": "local",
      "namespace": "my-wordpress-site",
      "status": "deployed",
      "version": "1.0.0",
      "deployedAt": "2026-01-06T12:00:00Z"
    },
    "production": {
      "clusterName": "production",
      "provider": "aws",
      "region": "us-west-2",
      "namespace": "my-wordpress-site",
      "status": "deployed",
      "version": "1.0.0",
      "deployedAt": "2026-01-07T14:00:00Z"
    }
  },
  "settings": {
    "defaultNamespace": "my-wordpress-site",
    "labels": {
      "app.kubernetes.io/managed-by": "displace",
      "environment": "production"
    },
    "annotations": {
      "displace.tech/project": "my-wordpress-site"
    }
  }
}

View Project Configuration

displace project info

Expected output:

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

Template:     wordpress (v27.0.0)
Namespace:    my-wordpress-site
Created:      2026-01-05 10:30:00

Deployments:
  displace-local (local)
    Status:    deployed
    Deployed:  2026-01-06 12:00:00

  production (aws/us-west-2)
    Status:    deployed
    Deployed:  2026-01-07 14:00:00

Project Credentials

Sensitive values are stored in .credentials (automatically git-ignored).

.credentials File

# Database Credentials
DB_ROOT_PASSWORD=generated_root_password_here
DB_PASSWORD=generated_db_password_here

# WordPress Credentials
WORDPRESS_USERNAME=admin
WORDPRESS_PASSWORD=generated_wp_password_here

# WordPress Security Keys
AUTH_KEY=random_64_char_string
SECURE_AUTH_KEY=random_64_char_string
LOGGED_IN_KEY=random_64_char_string
NONCE_KEY=random_64_char_string
AUTH_SALT=random_64_char_string
SECURE_AUTH_SALT=random_64_char_string
LOGGED_IN_SALT=random_64_char_string
NONCE_SALT=random_64_char_string

# Registry Configuration
REGISTRY_URL=k3d-displace-registry:5000

# Version Configuration
PHP_VERSION=8.3
WORDPRESS_VERSION=6.9.4

Using Credentials in Makefile

The Makefile automatically loads .credentials:

# Load environment variables from .credentials if it exists
ifneq (,$(wildcard .credentials))
    include .credentials
    export
endif

Overriding Credentials

# Override via environment variable
DB_PASSWORD=custom_password make deploy

# Override via command line
make deploy DB_PASSWORD=custom_password

Environment Variables

Environment variables provide the highest priority configuration.

Global Variables

Variable	Description	Default
`DISPLACE_CONFIG_DIR`	Configuration directory	`~/.displace`
`DISPLACE_NO_COLOR`	Disable colored output	`false`
`DISPLACE_VERBOSE`	Enable verbose output	`false`
`KUBECONFIG`	Kubernetes config path	`~/.kube/config`

Provider Variables

Variable	Description
`AWS_PROFILE`	AWS credentials profile
`AWS_REGION`	AWS region
`AWS_ACCESS_KEY_ID`	AWS access key
`AWS_SECRET_ACCESS_KEY`	AWS secret key
`GOOGLE_APPLICATION_CREDENTIALS`	GCP service account file
`DIGITALOCEAN_TOKEN`	DigitalOcean API token

Project Variables

Variable	Description
`PROJECT_NAME`	Project name override
`NAMESPACE`	Kubernetes namespace
`DOMAIN`	Application domain
`IMAGE_TAG`	Docker image tag
`REGISTRY_URL`	Container registry URL

Example Usage

# Deploy with custom namespace
NAMESPACE=staging displace project deploy --cluster production

# Build with custom image tag
IMAGE_TAG=v1.2.3 make build

# Use specific AWS profile
AWS_PROFILE=production displace cluster create prod --provider aws

Template Variables

Each template defines its own variables during displace project init.

Common Template Variables

Variable	Description	Example
`ProjectName`	Project identifier	`my-wordpress-site`
`Namespace`	Kubernetes namespace	`my-wordpress-site`
`Domain`	Application domain	`blog.example.com`

WordPress Template Variables

Variable	Default	Description
`PHPVersion`	`8.3`	PHP version
`WordPressVersion`	`6.9.4`	WordPress version
`WordPressReplicas`	`1`	Number of WordPress pods
`WordPressStorageSize`	`10Gi`	Uploads PVC size
`MariaDBStorageSize`	`8Gi`	Database PVC size
`MemoryLimit`	`512Mi`	Container memory limit
`CPULimit`	`500m`	Container CPU limit

Laravel Template Variables

Variable	Default	Description
`PHPVersion`	`8.3`	PHP version
`LaravelReplicas`	`2`	Number of Laravel pods
`AppStorageSize`	`5Gi`	Laravel storage PVC size
`DBStorageSize`	`10Gi`	MySQL PVC size

Viewing Template Variables

# Show template details and variables
displace template info wordpress

Manifest Configuration

Kubernetes manifests in manifests/ can be customized.

Manifest Files

manifests/
├── 01-namespace.yaml        # Namespace definition
├── 02-database-secret.yaml  # Database credentials
├── 03-mariadb.yaml          # Database deployment
├── 04-wordpress.yaml        # Application deployment
├── 05-ingress.yaml          # Ingress configuration
└── secrets/                 # Secret overrides (git-ignored)
    └── database-secret-override.yaml

Customizing Resources

Edit the manifest files directly:

# manifests/04-wordpress.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: wordpress
spec:
  replicas: 3  # Increase replicas
  template:
    spec:
      containers:
      - name: wordpress
        resources:
          limits:
            memory: "1Gi"  # Increase memory
            cpu: "1000m"   # Increase CPU

Using Kustomize

For environment-specific configuration:

manifests/
├── base/
│   ├── kustomization.yaml
│   └── *.yaml
├── overlays/
│   ├── development/
│   │   └── kustomization.yaml
│   ├── staging/
│   │   └── kustomization.yaml
│   └── production/
│       └── kustomization.yaml

Update Configuration

Displace auto-update settings are stored in ~/.displace/update_config.json:

{
  "autoUpdateEnabled": true,
  "checkInterval": "1h",
  "lastCheckAt": "2026-01-07T10:00:00Z",
  "notifyOnly": false
}

Configure Updates

# Enable auto-updates (default)
displace update --enable-auto

# Disable auto-updates
displace update --disable-auto

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

# View update configuration
displace update --configure

Configuration Best Practices

Version Control

# Always commit
git add manifests/ Makefile Dockerfile README.md

# Never commit
# .credentials (contains passwords)
# .displace/ (local state)
# uploads/ (user content)

Environment Separation

# Use different namespaces
NAMESPACE=myapp-dev displace project deploy --cluster displace-local
NAMESPACE=myapp-staging displace project deploy --cluster staging
NAMESPACE=myapp-prod displace project deploy --cluster production

Secrets Management

Development: Use .credentials file
Staging/Production: Use Kubernetes Secrets or external secrets manager
Never commit secrets to version control

Configuration Validation

# Validate manifests before deploying
make validate

# Or with kubectl
kubectl apply --dry-run=client -f manifests/

Troubleshooting

Configuration Not Loading

# Check file exists
ls -la ~/.displace/config.json
ls -la .displace/project.json

# Check file permissions
chmod 600 ~/.displace/config.json

# Validate JSON syntax
cat ~/.displace/config.json | jq .

Environment Variable Not Working

# Verify variable is set
echo $NAMESPACE

# Export before running
export NAMESPACE=my-namespace
displace project deploy

# Or inline
NAMESPACE=my-namespace displace project deploy

Credentials Not Found

# Check .credentials exists
ls -la .credentials

# Verify it's being loaded
make info

Configuration

Project Configuration

Configuration Hierarchy

Global User Configuration

Directory Structure

config.json

Configuring Providers

Project Configuration

Project Directory Structure

project.json

View Project Configuration

Project Credentials

.credentials File

Using Credentials in Makefile

Overriding Credentials

Environment Variables

Global Variables

Provider Variables

Project Variables

Example Usage

Template Variables

Common Template Variables

WordPress Template Variables

Laravel Template Variables

Viewing Template Variables

Manifest Configuration

Manifest Files

Customizing Resources

Using Kustomize

Update Configuration

Configure Updates

Configuration Best Practices

Version Control

Environment Separation

Secrets Management

Configuration Validation

Troubleshooting

Configuration Not Loading

Environment Variable Not Working

Credentials Not Found

Related Documentation

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Getting Started

Providers

Templates

Development

Guides

Infrastructure

Reference

Clone this wiki locally