Skip to main content
Version: Next

DDEV Installation (Recommended)

DDEV is the recommended way to develop Thelia 3 locally. It gives you a pre-configured Docker environment that behaves the same on every machine.

Prerequisites​

  1. Docker Desktop (Mac/Windows) or Docker Engine (Linux)
  2. DDEV (Installation Guide)

Quick installation​

Building a store​

Start from the project skeleton. Thelia 3.0.0-beta1 is a pre-release, so Composer only selects it when the beta stability is allowed:

composer create-project thelia/thelia-project my-shop --stability=beta
cd my-shop

ddev config --project-type=symfony --docroot=public
ddev start
ddev exec php bin/install --frontoffice_theme=flexy

Contributing to Thelia​

Clone the repository instead, which already ships a .ddev/ configuration:

# Clone Thelia 3
git clone https://github.com/thelia/thelia.git
cd thelia

# Start DDEV
ddev start

# Install dependencies
ddev composer install

# Install Thelia (Twig front-office + Twig back-office)
ddev exec php bin/install --frontoffice_theme=flexy

# Build the theme assets (required for both Twig themes)
ddev exec bash -c "cd templates/frontOffice/flexy && npm install && npm run build"
ddev exec bash -c "cd templates/backOffice/default-twig && npm install && npm run build"

# Open in browser
ddev launch

Your site is now accessible at https://thelia.ddev.site

The hostname follows the directory name

Thelia's .ddev/config.yaml sets no name key, so DDEV derives the project name from the directory you cloned into. git clone https://github.com/thelia/thelia.git creates a thelia/ directory and gives you https://thelia.ddev.site; a my-shop/ directory gives you https://my-shop.ddev.site. Run ddev describe to see the URLs of the current project.

Build the theme assets

The flexy front-office theme — and any Twig back-office theme such as default-twig — ship their assets as source and must be built with Webpack Encore. Skip this and the page fails with "Could not find the entrypoints file from Webpack". For a Twig back-office: ddev exec bash -c "cd templates/backOffice/default-twig && npm install && npm run build".

tip

bin/install reads database credentials from DDEV's environment automatically (DATABASE_HOST=db, DATABASE_NAME=db, etc.). You do not need to pass any database options.

Install with demo data and admin​

ddev exec php bin/install \
    --frontoffice_theme=flexy \
    --with-demo \
    --with-admin \
    --admin_login=admin \
    --admin_password=admin123 \
    --admin_email=admin@example.com
The back-office theme defaults to default-twig

--backoffice_theme defaults to default-twig, the Twig back-office, so you do not need to pass it. Pass --backoffice_theme=default only if you deliberately want the legacy Smarty admin; that admin is not built on the Twig hook functions, and a Twig template that calls safe_hook() throws Unknown "safe_hook" function when the Twig back-office bundle is not the active one.

See Install Reference for all available options and environment variables.

DDEV commands reference​

Daily commands​

ddev start                  # Start environment
ddev stop                   # Stop environment
ddev restart                # Restart
ddev ssh                    # SSH into container
ddev describe               # View project info
ddev launch                 # Open in browser

Running PHP commands​

ddev exec php Thelia cache:clear
ddev exec php Thelia module:list
ddev exec php Thelia module:activate ModuleName
ddev exec php Thelia admin:create

Composer​

ddev composer install
ddev composer require vendor/package

Database​

ddev mysql                           # MySQL CLI
ddev import-db --file=dump.sql.gz    # Import
ddev export-db --file=dump.sql.gz    # Export
ddev snapshot                        # Create snapshot
ddev snapshot restore                # Restore snapshot

Logs​

ddev logs                   # View logs
ddev logs -f                # Follow mode
ddev logs -s web            # Web server logs
ddev logs -s db             # Database logs

Accessing services​

Replace thelia with your own directory name if you cloned or created the project elsewhere.

ServiceURL
Front-officehttps://thelia.ddev.site
Back-officehttps://thelia.ddev.site/admin
Mailpithttps://thelia.ddev.site:8026

Theme development​

ddev ssh
cd templates/frontOffice/flexy
npm install
npm run dev    # Watch mode
npm run build  # Production

Troubleshooting​

Port conflicts​

ddev poweroff    # Stop all DDEV projects
ddev start       # Restart

Permission issues​

ddev exec chmod -R 777 var/cache var/log

Complete reset​

ddev delete -O
ddev start
ddev exec php bin/install --frontoffice_theme=flexy

Next steps​