---
title: "Quickstart"
description: "From installing the add-on to the first usable worktree."
canonical: quickstart.html
navigation-title: "Quickstart"
---
- [Before you install](#before-you-install)
- [Install Branchery](#install-branchery)
- [Commit what was installed](#commit-what-was-installed)
- [Describe how the project is built](#describe-how-the-project-is-built)
- [Create the first worktree](#create-the-first-worktree)
- [Check the result](#check-the-result)
- [Continue from here](#continue-from-here)
# Quickstart
From installing the add-on to the first usable worktree. Every step is one
command, and the interface does the same thing with a press.
## Before you install
The project must already run in DDEV and its root must be a git repository.
Branchery uses the project's web and database containers, so start from a
working project rather than from an empty DDEV configuration.
> [!WARNING]
> nginx is not supported; the project must be served by Apache. Under Apache
> every worktree reads the `.htaccess` of its own branch, while nginx
> serves it through one generic server block that the rewrite rules in the
> project's own nginx configuration do not reach. Switch before installing:
>
> ```bash
> ddev config --webserver-type=apache-fpm
> ddev restart
> ```
> [!WARNING]
> The Branchery API is intentionally unauthenticated. Keep its port on the
> developer's own machine behind DDEV's router; do not expose it on a shared
> or public network.
## Install Branchery
Run these commands in the project root:
```bash
ddev add-on get benjaminkott/ddev-branchery
ddev restart
```
The management interface is now available at
`https://.ddev.site:8041`. Open it with:
```bash
ddev branchery launch
```
The project checkout keeps answering at `https://.ddev.site`.
## Commit what was installed
The add-on leaves a handful of files in `.ddev/`. They are committed with the
project, which is DDEV's convention for an add-on: a clone then has Branchery
without installing it, and on the version the project chose.
```text
.ddev/addon-metadata/branchery/ which version is installed
.ddev/commands/host/branchery the "ddev branchery" command
.ddev/config.branchery.yaml the wildcard hostname of the worktrees
.ddev/docker-compose.branchery.yaml the service and the image tag it runs
.ddev/web-entrypoint.d/branchery.sh what the web container runs on start
```
What stays out is the working state. `.ddev/branchery/var/` and
`.worktrees/` each carry a rule of their own, and the project's own
`.gitignore` is never written to.
## Describe how the project is built
Branchery does not infer an application's setup from its files. Choose the
shipped profile that matches the project:
| Profile | Use it for |
| --- | --- |
| `typo3-app` | a TYPO3 instance, or an extension that builds one |
| `typo3-core` | the TYPO3 core repository, served from its own root |
| `symfony` | a Symfony application |
| `composer` | a project that only needs `composer install` |
Write the starting configuration, for example:
```bash
ddev branchery config:example --profile=typo3-app --write
```
This creates `.ddev/branchery.yaml`. Commit it with the project so the team
and every branch share the setup. Print the complete shipped profile before
customizing it with:
```bash
ddev branchery config:example --profile=typo3-app --full
```
The [configuration reference](../reference/configuration.md) explains how a project
changes its docroot, setup commands, data source and carried files. Without
this file a worktree is only a checkout at an address of its own, with an empty
database.
## Create the first worktree
Use `fork` when the branch does not exist yet and should start from the
current project checkout:
```bash
ddev branchery worktree:fork feature/checkout
```
Use `add` when the branch already exists locally or on a remote:
```bash
ddev branchery worktree:add 13.4
```
A fork may start from another worktree instead of the project checkout:
```bash
ddev branchery worktree:fork follow-up --from=feature-checkout
```
Branchery makes the name safe for a hostname. A branch called
`feature/checkout` is normally served at:
```text
https://feature-checkout..ddev.site
```
The git branch keeps its original name. Use `--name=` only when the
directory, address and database need a different safe name.
## Check the result
List what Branchery created:
```bash
ddev branchery worktree:list
```
The row names the address, branch, PHP version and database. It also shows
whether the build finished and whether dependencies have changed since it was
built. `ddev describe` carries the same addresses in its Branchery section.
Open the worktree URL and the Branchery interface. A finished operation has a
step-by-step record on the worktree page; a stopped one includes the command
that continues from a safe point. See [Troubleshooting](../use-branchery/troubleshooting.md) when the first
build does not finish.
## Continue from here
The overview now has a row for the worktree. [Working with worktrees](../use-branchery/worktrees.md) says what that
row tells you, how to keep the worktree current and how to remove it when its
work has landed. Open the checkout in an editor next: [Editors](../use-branchery/editors.md) says what
Branchery has written into it for the debugger and what each window has to
leave out. When a build stops, [Troubleshooting](../use-branchery/troubleshooting.md) has the way on.
[Configuration reference](../reference/configuration.md) is the project's file, key by key, and [Worktree operations](../reference/operations.md)
every operation, step by step. Updating and uninstalling the add-on are on
[Update and uninstall](update.md).