Ga naar inhoud

Lando Local Development

Table of Contents

Overview

Lando is a local development tool that allows developers to easily spin up local development environments for WordPress and other applications.

Benefits: - Quick setup of local development environments - Consistent development environments across team - Built on Docker (but easier to use) - Includes common tools (WP-CLI, Composer, Node, etc.) - SSL certificates out of the box

Official documentation: lando.dev

Installation

Step 1: Download Lando

Download the latest .dmg package from GitHub Releases

Warning

Choose the correct DMG for your chip architecture: - Apple Silicon (M1/M2/M3): Download the arm64 version - Intel Macs: Download the x64 version Not sure which chip you have? See: Which Chipset Do I Have?

Step 2: Install

  1. Open the downloaded .dmg file
  2. Double-click the LandoInstaller.pkg file
  3. Follow the installation steps
  4. Enter your username or password when prompted

Alternative: Homebrew

If you prefer Homebrew:

brew install --cask lando

Note: If you don't have Homebrew installed, see: Homebrew Installation

Verify Installation

lando version

You should see the Lando version number.

Configuration

Project Setup

Every Lando project requires a .lando.yml configuration file in the project root.

Basic Configuration

File: /site/.lando.yml

# Project name (will be accessible at projectname.lndo.site)
name: hetccv

# Recipe (WordPress, Drupal, Laravel, etc.)
recipe: wordpress

# Configuration
config:
  # PHP version
  php: "8.2"

  # Web server (nginx or apache)
  via: nginx

  # Document root (for Bedrock, this is 'web')
  webroot: web

  # Xdebug configuration
  xdebug: "debug,develop,trace"

# Services
services:
  database:
    type: mariadb:10.6

Environment Variables

File: /site/.env

# Database configuration (matches Lando defaults)
DB_NAME=wordpress
DB_USER=wordpress
DB_PASSWORD=wordpress
DB_HOST=database

# WordPress environment
WP_ENV=development

# Site URL (must match 'name' in .lando.yml)
WP_HOME=http://hetccv.lndo.site
WP_SITEURL=${WP_HOME}/wp

Starting a New Project

Step 1: Create Configuration Files

Create .lando.yml and .env files as shown above.

Step 2: Start Lando

cd /path/to/project/site
lando start

Step 3: Access Your Site

Your site will be available at: http://projectname.lndo.site

Step 4: Import Database (Optional)

# Import database
lando db-import backup.sql

# Or sync from production
./scripts/database-sync.sh

Advanced Configuration

Custom Services

Add additional services to .lando.yml:

services:
  # ElasticSearch
  elasticsearch:
    type: elasticsearch:7
    portforward: 9200

  # Redis
  redis:
    type: redis:6

  # MailHog (email testing)
  mailhog:
    type: mailhog
    portforward: 1025
    hogfrom:
      - appserver

Tooling Commands

Add custom commands:

tooling:
  npm:
    service: appserver
    cmd: npm

  yarn:
    service: appserver
    cmd: yarn

  composer:
    service: appserver
    cmd: composer

Build Steps

Run commands during Lando start:

services:
  appserver:
    build:
      - composer install
      - npm install
    run:
      - npm run build

Useful Commands

Basic Commands

Start Lando: 

lando start

Stop Lando: 

lando stop

Restart Lando: 

lando restart

Rebuild Lando: 

lando rebuild -y

Destroy Lando Environment: 

lando destroy -y

View Info: 

lando info

WP-CLI Commands

Lando includes WP-CLI by default:

Create Admin User: 

lando wp user create admin admin@site.local --role=administrator --user_pass=admin

Reset Admin Password: 

lando wp user update admin --user_pass=admin

Search and Replace: 

lando wp search-replace 'https://production.com' 'http://project.lndo.site' --all-tables

Flush Cache: 

lando wp cache flush

Export Database: 

lando wp db export backup.sql

Import Database: 

lando wp db import backup.sql

List All Users: 

lando wp user list

Check WordPress Version: 

lando wp core version

Composer Commands

# Install dependencies
lando composer install

# Update dependencies
lando composer update

# Require package
lando composer require vendor/package

Node/NPM Commands

# Install packages
lando npm install

# Run build
lando npm run build

# Watch for changes
lando npm run watch

Database Commands

Import Database: 

lando db-import backup.sql

Export Database: 

lando db-export backup.sql

Access Database: 

lando mysql

Connect with External Tool: 

# Get database credentials
lando info

# External port will be shown (usually 127.0.0.1:32XXX)

SSH into Container

# SSH into app server
lando ssh

# SSH into database
lando ssh -s database

Logs

View Logs: 

lando logs

# Follow logs
lando logs -f

# Service-specific logs
lando logs -s appserver
lando logs -s database

Troubleshooting

Common Issues

Port Already in Use

Error: 

Port 80 is already in use

Solution: 

# Check what's using port 80
lsof -i :80

# Stop the conflicting service or change Lando's port

Change port in .lando.yml: 

proxy:
  appserver:
    - projectname.lndo.site:8080

Certificate Error

Error: 

EISDIR: illegal operation on a directory, open '/Users/username/.lando/certs/appserver.project.crt'

Solution: 

cd ~/.lando/certs
rm -rf appserver.project.*
lando rebuild -y

Database Connection Error

Symptoms: - "Error establishing database connection" - Can't connect to database

Solution: 

# Check database is running
lando info

# Restart Lando
lando restart

# Verify .env database credentials
DB_HOST=database
DB_NAME=wordpress
DB_USER=wordpress
DB_PASSWORD=wordpress

Slow Performance

On macOS with large projects:

Add to .lando.yml:

services:
  appserver:
    overrides:
      volumes:
        - /app/web/app/uploads
        - /app/node_modules
        - /app/vendor

This excludes large directories from file syncing.

Permission Issues

# Fix file permissions
lando ssh
chown -R www-data:www-data /app/web/app/uploads
chmod -R 755 /app/web/app/uploads

Xdebug Not Working

Check Xdebug is enabled: 

lando php -v | grep Xdebug

Configure IDE (VS Code):

Add to .vscode/launch.json: 

{
  "name": "Listen for Xdebug",
  "type": "php",
  "request": "launch",
  "port": 9003,
  "pathMappings": {
    "/app": "${workspaceFolder}/site"
  }
}

Lando Commands Not Found

Restart your terminal or add Lando to PATH:

# Add to ~/.zshrc or ~/.bashrc
export PATH="/usr/local/bin:$PATH"

Out of Disk Space

Clean up Docker: 

# Remove unused Docker images
lando poweroff
docker system prune -a

Advanced Usage

Multiple PHP Versions

services:
  appserver:
    type: php:8.2

  appserver_php74:
    type: php:7.4
    webroot: web

Custom Domain

proxy:
  appserver:
    - custom-domain.test

Add to /etc/hosts: 

127.0.0.1 custom-domain.test

Running Tests

tooling:
  phpunit:
    service: appserver
    cmd: vendor/bin/phpunit

Usage: 

lando phpunit

Performance Tips

  1. Use NFS for better file sync performance (macOS)
  2. Exclude large directories from sync (node_modules, vendor)
  3. Increase Docker resources (CPU, Memory in Docker Desktop)
  4. Use latest Lando version (performance improvements in new releases)
  5. Disable Xdebug when not debugging

See Also