Skip to content

configuration.md

Latest commit

 

History

History
228 lines (172 loc) · 5.97 KB

configuration.md

File metadata and controls

228 lines (172 loc) · 5.97 KB

Configuration

Configuration file format and local file structure for elementor-cli.

Config File

Location: .elementor-cli.yaml (project root)

Important: Add to .gitignore - this file contains credentials.

Full Example

# Default site for commands when --site is not specified
defaultSite: production

# Remote WordPress sites
sites:
  production:
    url: https://my-friends-site.de
    username: admin
    appPassword: xxxx xxxx xxxx xxxx xxxx xxxx
    # Auto-create revision before every push (default: false)
    createRevisions: true
    # Container running WordPress (for CSS cache flush via WP-CLI)
    container:
      runtime: docker    # "docker" or "podman"
      name: my-wordpress-container

  staging-remote:
    url: https://staging.my-friends-site.de
    username: admin
    appPassword: yyyy yyyy yyyy yyyy yyyy yyyy
    createRevisions: false  # Fast iteration on staging

# Local staging environment configuration
staging:
  # Path to docker-compose.yml (relative to project root)
  path: ./docker

  # WordPress service name in docker-compose.yml
  service: wordpress

  # Local staging URL
  url: http://localhost:8080

  # WP-CLI command (useful if wp is not in PATH or uses a different name)
  wpCommand: wp  # or "php wp-cli.phar" or path to wp-cli

  # Container runtime for staging commands (default: "docker")
  containerRuntime: docker  # "docker" or "podman"

# Local pages storage directory
pagesDir: .elementor-cli/pages

Site Configuration

Each site requires:

Field Required Description
url Yes WordPress site URL (must be HTTPS)
username Yes WordPress admin username
appPassword Yes Application Password (generate in WordPress admin)
createRevisions No Auto-create revision before push (default: false)
container No Container config for WP-CLI CSS flush (see below)

Container Configuration (per-site)

If a site runs inside a Docker/Podman container, configure container to enable WP-CLI-based CSS cache flushing after push:

Field Required Description
runtime Yes Container runtime: "docker" or "podman"
name Yes Container name or ID

Staging Configuration

Field Default Description
path .elementor-cli/staging Path to docker-compose.yml
service wordpress WordPress service name in compose file (which container has WP-CLI)
url http://localhost:8080 Local staging URL
wpCommand wp WP-CLI command to use (e.g., php wp-cli.phar if wp is not in PATH)
containerRuntime docker Container runtime for staging commands: "docker" or "podman"

Generating Application Passwords

  1. Log into WordPress admin
  2. Go to Users → Profile
  3. Scroll to Application Passwords
  4. Enter a name (e.g., "elementor-cli")
  5. Click Add New Application Password
  6. Copy the generated password (spaces included)

Enabling Application Passwords over HTTP (Local Development)

WordPress only allows Application Passwords over HTTPS by default. For local development environments using HTTP, you need to install a must-use plugin.

Create the file wp-content/mu-plugins/enable-app-passwords-http.php:

<?php
// Enable Application Passwords over HTTP for local development
add_filter('wp_is_application_passwords_available', '__return_true');
add_filter('application_password_is_api_request', '__return_true');

Warning: Only use this on local development environments. Never deploy this to production sites.

Local File Structure

my-project/
├── .elementor-cli.yaml             # Project config (add to .gitignore!)
├── .elementor-cli/
│   ├── pages/
│   │   └── production/             # Per-site storage
│   │       ├── 42/
│   │       │   ├── page.json       # Complete page data
│   │       │   ├── elements.json   # Editable element tree
│   │       │   ├── settings.json   # Page settings
│   │       │   └── meta.json       # Title, slug, status
│   │       └── 156/
│   │           └── ...
│   ├── dumps/                      # Database dumps
│   │   ├── staging-2024-01-27-143052.sql
│   │   └── production-2024-01-26-091530.sql
│   ├── staging/                    # Only if using 'preview init'
│   │   └── docker-compose.yml
│   └── templates/                  # Starter templates
│       ├── blank.json
│       └── landing-page.json
├── docker/                         # Your existing Docker setup (example)
│   └── docker-compose.yml
└── .gitignore                      # Should include .elementor-cli.yaml

Page Storage

When you pull a page, it's stored in multiple files for easier editing:

page.json

Complete page data snapshot:

{
  "id": 42,
  "title": "Home",
  "slug": "home",
  "status": "publish",
  "elementor_data": [...],
  "page_settings": {...},
  "pulled_at": "2024-01-27T12:00:00Z",
  "remote_modified": "2024-01-15T10:30:00Z"
}

elements.json

Just the Elementor element tree - this is what you edit:

[
  {
    "id": "abc123",
    "elType": "container",
    "settings": {...},
    "elements": [...]
  }
]

settings.json

Page-level settings:

{
  "background_background": "classic",
  "background_color": "#ffffff",
  "padding": {...}
}

meta.json

WordPress post metadata:

{
  "title": "Home",
  "slug": "home",
  "status": "publish"
}

.gitignore Recommendations

Add these to your .gitignore:

# Elementor CLI credentials
.elementor-cli.yaml

# Database dumps (optional - may want to keep these)
.elementor-cli/dumps/

# Local staging environment
.elementor-cli/staging/

Keep page data in git if you want version control:

# Track page changes in git
!.elementor-cli/pages/