> For the complete documentation index, see [llms.txt](https://docs.varbase.vardot.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.varbase.vardot.com/developers/installing-varbase/installing-varbase-with-ddev.md).

# Installing Varbase locally with DDEV

This guide walks you through installing Varbase 11.0.x on your local machine using [DDEV](https://ddev.readthedocs.io/), a Docker-based local development tool designed for PHP projects.

## Prerequisites

Before you begin, make sure you have the following installed on your machine:

1. **Docker**: DDEV requires Docker (or a compatible container runtime such as Colima or OrbStack).
   * Install Docker Desktop from <https://www.docker.com/products/docker-desktop/>
2. **DDEV**: Install DDEV by following the official installation guide:
   * <https://ddev.readthedocs.io/en/stable/users/install/>

## Step 1: Create the Project Directory

Create a new directory for your Varbase project and navigate into it:

```bash
mkdir my_varbase_site
cd my_varbase_site
```

Replace `my_varbase_site` with your desired project directory name.

## Step 2: Configure DDEV

Run the DDEV configuration command with the following options:

```bash
ddev config --project-type=drupal11 --docroot=web --php-version=8.4
```

This configures the project as a Drupal 11 site with:

* **Docroot**: `web` (the Varbase web root).
* **PHP version**: `8.4`.
* **Project name**: Defaults to the directory name.

## Step 3: Start DDEV

Start the DDEV environment:

```bash
ddev start
```

This command pulls the required Docker images, creates the containers, and starts the development environment. The first run may take a few minutes.

## Step 4: Create the Varbase Project

Use Composer inside DDEV to create the Varbase project:

```bash
ddev composer create-project "drupal/varbase_project:~11.0.0"
```

This downloads Varbase and all of its dependencies (Drupal core, contributed modules, recipes, themes, and libraries) into the project directory.

Composer only downloads the code. The site is installed in the next step.

## Step 5: Run the Installer

Open the site in a browser:

```bash
ddev launch
```

The **Varbase installer** opens. On the **Choose a site template** step, keep **Varbase Starter** or pick another site template you added to the project with Composer, then give the site a name. The installer applies the site template and its recipes:

* Drupal CMS 2 recipes (anti-spam, authentication, forms, SEO basic and SEO tools, accessibility tools and search)
* Varbase recipes (users, admin, security, media, editor, content, Canvas, workflow, search, SEO, webform, page, blog, performance and demo content)
* Easy Email recipes for HTML email
* Vartheme BS5 as the front-end theme and Gin as the admin theme

To install without the browser, run `ddev install-varbase minimal` (see below) or `ddev drush site:install varbase`.

## Complete Installation Commands

Here are all the commands together for quick reference:

```bash
mkdir my_varbase_site
cd my_varbase_site
ddev config --project-type=drupal11 --docroot=web --php-version=8.4
ddev start
ddev composer create-project "drupal/varbase_project:~11.0.0"
ddev launch
```

## Useful DDEV Commands

| Command                   | Description                                 |
| ------------------------- | ------------------------------------------- |
| `ddev start`              | Start the project containers                |
| `ddev stop`               | Stop the project containers                 |
| `ddev restart`            | Restart the project containers              |
| `ddev launch`             | Open the site in your default browser       |
| `ddev drush [command]`    | Run a Drush command inside the container    |
| `ddev composer [command]` | Run a Composer command inside the container |
| `ddev ssh`                | SSH into the web container                  |
| `ddev describe`           | Show project information and URLs           |

### Custom DDEV Commands for Varbase <a href="#ddev-commands" id="ddev-commands"></a>

#### `ddev install-varbase` <a href="#ddev-install-varbase" id="ddev-install-varbase"></a>

Installs Varbase from scratch using `drush site:install varbase` with the Varbase profile and Drupal recipes.

```
# Minimal install: core Varbase only (no extra recipes)
ddev install-varbase minimal

# Full install: core + dev, i18n, api, auth recipes + social auth modules
ddev install-varbase full
```

#### `ddev init-full-automated-testing` <a href="#ddev-init-full-automated-testing" id="ddev-init-full-automated-testing"></a>

Full initialization for automated testing. Handles everything from a fresh `ddev start`:

1. Installs Varbase if the database is empty
2. Applies optional Varbase recipes (`varbase_dev_base`, `varbase_i18n_base`, `varbase_api_base`, `varbase_auth_base`, `varbase_ai_base`)
3. Enables social auth modules (`social_auth_facebook`, `social_auth_linkedin`)
4. Adds testing users for each Varbase role
5. Disables the antibot module (required for automated browser testing)
6. Disables CSS/JS aggregation
7. Sets verbose error logging

#### `ddev init-minimal-automated-testing` <a href="#ddev-init-minimal-automated-testing" id="ddev-init-minimal-automated-testing"></a>

Minimal initialization for automated testing on an already installed site. Does not install Varbase or apply recipes:

1. Verifies Drupal is installed (exits with error if not)
2. Adds testing users for each Varbase role
3. Disables the antibot module
4. Disables CSS/JS aggregation
5. Sets verbose error logging

#### `ddev add-testing-users` / `ddev delete-testing-users` <a href="#ddev-add-testing-users-ddev-delete-testing-users" id="ddev-add-testing-users-ddev-delete-testing-users"></a>

Manage testing user accounts individually.

## Troubleshooting

* If `ddev start` fails, ensure Docker is running and that no other services are using the same ports.
* Run `ddev poweroff` followed by `ddev start` to reset the DDEV environment if you encounter persistent issues.
* Check DDEV logs with `ddev logs` for detailed error information.