Local development against Acquia

Goal: a sustainable local routine: data flowing down from environments when you need it, code flowing back up through git, and nothing else moving at all.

Local development is cross-path: the same setup serves an in-platform-rendering site you theme and a headless backend you query. If you’d rather run nothing locally, Cloud IDE is the hosted alternative; everything below has an equivalent there.

What you’ll have when you’re done

• A refresh routine for stale local data, in one command.
• The one-way rules: configuration travels in code, content stays on environments, local databases never go upstream.
• A clear picture of the alternatives (Lando, plain acli, Cloud IDE) and when each fits.

Prerequisites

• A working local site from the local dev quickstart
• The deploy loop from the code-workflow quickstart

Steps

1. Refresh local data whenever it goes stale

   With the DDEV setup from the quickstart, it’s the same command every time:

   ddev pull acquia

   Without DDEV’s integration, acli does the same two moves directly:

   acli pull:db myapp.dev
   acli pull:files myapp.dev

   Pull from the environment whose data shape you’re working against: usually myapp.dev or myapp.test (the alias of the environment labeled Stage); myapp.prod when you’re chasing a data-dependent bug.

2. Let configuration travel in code, not in the database

   Drupal configuration (content types, fields, settings) exports to the config/ directory, which means it rides the same git → environment path as code. The local half of the habit: export after you change configuration, commit what changed, and run the import on the environment after deploy:

   ddev drush config:export
   git add config/ \
     && git commit -m "Add teaser display to articles"
   git push origin dev
   acli remote:drush myapp.dev -- config:import

   Manage configuration covers where the sync directory belongs in a Cloud Platform repository and how to run the import from a Cloud Hook instead of by hand. It also shows how to stop an import reverting what editors changed in production. For what belongs in configuration vs. content, see drupal.org/docs.

3. Push code up; never push data up

   Work leaves your machine one way: git push, exactly as in the code-workflow quickstart. Local databases and files stay local: an upstream copy would overwrite content editors changed since you pulled. The moment you’re tempted to push a database, what you actually want is step 2 (the change expressed as configuration) or a content deployment process on the environment side.

4. Know the alternatives, and when to switch

   • Lando: the other mainstream container-based local stack, with its own Acquia recipe. If your team already runs Lando, keep it and follow Lando’s Acquia recipe docs; the pull/refresh concepts below map one-to-one.
   • Plain acli: acli pull:db / acli pull:files feed any local stack you already maintain (native PHP, your own containers). You run the web server; acli moves the data.
   • Cloud IDE. Nothing installed at all: a browser-based environment on Acquia’s infrastructure, preauthenticated with the platform, so acli works in its terminal without a login and the pull commands above behave identically. The right answer on locked-down machines, for quick fixes, and for onboarding someone before their local stack exists. Adding one to your subscription, creating it, and its resource limits are on Acquia’s Cloud IDE documentation.

When something goes wrong

Local site breaks right after a refresh

the pulled database expects different code (a module or update the environment has and your checkout doesn’t). Check out the branch that environment tracks (shown on its environment card in the Cloud Platform user interface), then re-run the pull.

config:import on the environment fails or reports unexpected diffs

the environment’s active configuration drifted from what’s in config/ (someone changed settings in the UI on the environment). Export on the environment first to see the drift, reconcile in code, then import. Recurring drift on the same settings means those settings are managed on the environment, not in the repository; manage configuration covers that case, along with the site-UUID mismatch that makes an import fail outright.

Pulled files directory is huge and the pull crawls

pull the database alone (acli pull:db myapp.dev) and skip files until you need them; most local work never reads the files directory.

Next steps

• Code-workflow guide: environments, deploys, and data moves on the Acquia side.
• Manage configuration: step 2’s export/import habit, automated on deploy and made safe for production.
• Everyday CLI workflows: logs, databases, and remote drush beyond the pull commands.