Develop locally with DDEV

DDEV runs WordPress on your computer in Docker. Avaloi gives it an add-on, avaloi/ddev-avaloi, so one command makes a working copy of an environment: the code from Git, plus the database and uploads.

Three parts move between Avaloi and your computer. You pick which, every time.

Part	How it moves	Staging and multidevs	Live
Code	Git, through the Avaloi remote	Pull and push	Pull only
Database	SSH, or a backup download	Pull and push	Pull only, from a backup
Uploads	SSH, or a backup download	Pull and push	Pull only, from a backup

Live is read only. You can copy it down. You cannot send anything back to it. To change live, push to staging and promote.

What you need

• Docker and DDEV. On Windows, use WSL2 with Docker inside it, and keep the project in your Linux home folder, not under C:\. On macOS, use Docker Desktop, OrbStack, or Colima. On Linux, Docker Engine is enough.
• An SSH key on your Avaloi account. See Clone with Git.
• An API key with the sites:read scope, kept in your shell environment as AVALOI_API_KEY. Pulling from live, and pushing the database or uploads, also need backups:write and jobs:read, because live data comes from a backup and a push takes one first. Your computer needs bash, curl, jq, git, and tar. See API keys and scopes.

Set it up

1. Make a folder for the project and open a terminal there.

2. Install the add-on:

   ddev add-on get avaloi/ddev-avaloi
   

3. Connect it to the environment. init reads the settings from Avaloi, writes the DDEV files, and adds a Git remote named avaloi with the right address:

   ddev avaloi init my-site
   

   Add the environment name for a multidev or live: ddev avaloi init my-site qa. init asks for your API key if AVALOI_API_KEY is not set. It never writes the key to a file.

4. Restart DDEV so the new settings apply, and load your SSH key:

   ddev restart
   ddev auth ssh
   

5. Pull everything:

   ddev avaloi pull --all
   

6. Open the site with ddev launch. It runs at https://NAME.ddev.site.

Instead of step 2 and 3, the Local development card on Info has a Download starter button. It gives you a small zip with the DDEV settings for this one environment. It holds a host, a port, and a user name. It never holds a password or a key.

Pick the parts

pull and push take flags. Use any mix.

Flag	Moves
--code	The code, with Git
--db	The database
--uploads	The files in wp-content/uploads
--all	All three

ddev avaloi pull --db --uploads     # fresh data, keep your code
ddev avaloi pull --code             # new commits only
ddev avaloi push --code             # send your commits to staging
ddev avaloi push --db --uploads     # replace staging's data

With no flag in a terminal, the add-on asks which parts you want. A pull starts with all three ticked. A push starts with code only. In a script, with no terminal, you must pass a flag.

Code is plain Git

The add-on adds nothing special to code. init sets up the remote, and after that you can use Git yourself:

git pull avaloi main
git push avaloi main

Staging uses the branch main. A multidev uses env/NAME. A push builds a new release on the environment. See Git access.

ddev avaloi pull --code clones the repository the first time, into the project folder, so wp-content with its plugins and themes is the Git working tree. After that it runs git pull --ff-only. If your branch has diverged, or you have changes you have not committed, it stops and says so. It never throws away your work. Add --rebase to rebase your commits on top.

The add-on never deletes a file that is in the repository. That includes plugins, themes, and cache drop-ins that you committed.

To see the code live runs right now, use ddev avaloi code --release live. It checks out that commit and leaves you on a detached head. Live has no remote of its own: you read its code from the same repository as staging.

What a pull does and does not bring

• Code comes from Git. It includes WordPress core, plugins, and themes as the repository holds them.
• Database comes as a compressed dump. The add-on imports it and then rewrites the site address to your local one, in every table, including values WordPress stores in a serialized form. On a WordPress network it rewrites the network address too. It keeps your table prefix.
• Uploads come without caches, backup plugin archives, database dumps, logs, and PHP files. PHP does not run from uploads on Avaloi either.
• The Avaloi plugin is part of the server, not your repository, so it never comes down.
• The add-on removes a few Avaloi settings from the local copy of the database, such as a stored sign-in ticket. It does not touch your files.
• If a cache or database drop-in (advanced-cache.php, object-cache.php, db.php) is in your repository, it stays. The add-on warns that it is there. See Local development troubleshooting.

Push to staging

Only staging and multidevs take a push. Live never does.

• Code is a normal git push. The add-on checks the target is allowed and shows where to watch the build.
• Database and uploads replace what is on the environment. Before it sends anything, the add-on takes a backup through Avaloi, asks you to confirm, and then sends. Add --yes to skip the question in a script. The backup is in Backups, so a bad push is one restore away.

A pushed database replaces users, orders, and comments on staging. Push only when you mean to. Push uploads adds and updates files and never removes any.

Security

• A pulled database holds user emails and password hashes. Keep your disk encrypted.
• The add-on keeps your API key out of every file. Read it from your shell, or set AVALOI_API_KEY_COMMAND to a command that prints it, such as pass show avaloi. To rotate a key, make a new one in Account settings, change it in the one place you keep it, and revoke the old one.
• The .ddev folder, wp-config.php, and your local uploads stay out of Git. init lists them in .git/info/exclude. The whole repository is the web root, so a .ddev folder that reached the repository would be public.
• Avaloi records each pull and push in Activity, with the person or key. SSH traffic itself is not seen by Avaloi.

Not yet

• The add-on is not in the DDEV registry yet, and the avaloi/ddev-avaloi repository is not public yet. Until it is, install it from a local copy with ddev add-on get /path/to/ddev-avaloi.
• The add-on has run on Linux and on Windows with WSL2. Traditional Windows with Docker Desktop and macOS are not tested yet.
• Avaloi does not report the server's SSH host key yet, so the first connection trusts the host and pins it from then on. Avaloi will publish the fingerprint so the add-on can check it before the first connection.
• Local by WP Engine is not supported.

API

• GET /v1/environments/{id}/local-dev: the settings the add-on reads. It holds no secret.
• POST /v1/environments/{id}/local-dev/pull-session and POST /v1/environments/{id}/local-dev/push-session: record a pull or push in the activity log and return the plan.
• POST /v1/environments/{id}/backups, POST /v1/backups/{id}/download, and POST /v1/backups/{id}/download-link: how live data reaches your computer.

The MCP server offers get_local_dev_config. It is read only.

Related

• Pull a database and files
• Push code to staging
• Local development troubleshooting
• Clone with Git
• Git access
• SSH and SFTP
• Backups