Developing your site

Your instance is tuned for production. Caches are on, aggregation is on, errors are hidden, and a fast cache backend (Valkey) sits in front of the database. That is exactly what you want for a live site and exactly what gets in your way when you are building a theme or a module and need to see every change immediately.

The good news: you don't have to fight any of that, and you never need root or your host to do it. BOA gives you a development URL for every site, and everything you do on this page happens in your own shell (as oN.ftp) with Drush, plus a couple of files you are allowed to edit. Let's walk through it.

The .dev. preview URL

The trick that makes all of this pleasant is a special address. When you visit your site through a hostname that has .dev. in it, BOA quietly switches that page into development mode for you:

  • errors are shown on screen instead of hidden,
  • the internal page cache and CSS/JS aggregation are turned off,
  • opcode caching revalidates on every request, so edited PHP is picked up straight away.

Your normal live address is untouched the whole time. Real visitors keep seeing the fast, cached, error-free production site. Only requests that come in through the .dev. name get the development treatment. That means you can debug on the same running site, with the same database and files, without putting the live site into a fragile state.

Turning the development URL on

The development URL isn't magic wiring you have to request from anyone. It is just an alias of your site whose name contains .dev., and you add it yourself on the site's edit form in the control panel, the same place you add any other alias (see Site aliases and redirects).

Add an alias in this shape, with dev sitting between two dots:

www.dev.example.com

The .dev. in the middle is what both BOA's front end and the web server look for. A name like dev.example.com (with dev only at the start) will also flip the page into development mode, but the reliable, always-served form is the one with .dev. in the middle, so prefer www.dev.example.com or staging.dev.example.com.

A few practical notes:

  • Point the DNS for that name at your instance just like any other alias, or add it to your workstation's hosts file if it is only for your own eyes.
  • If your site has SSL enabled, the .dev. alias is covered too. BOA folds any alias with .dev. (or .devel.) in the middle into the site's HTTPS server and into its automatic Let's Encrypt certificate, so https://www.dev.example.com just works — no separate certificate to request. (The dev/devel exception only skips certificates when a site's main name is a dev name, not for a .dev. alias of a normal site.)
  • Nothing about the production site changes. You are adding a second door, not rebuilding anything.

Twig debugging and turning off the cache backend (Drupal 8+)

On the .dev. URL, BOA already relaxes Drupal's page cache and aggregation for you. Two things it does not turn on by itself, because they are choices only you should make, are Twig template debugging and bypassing the Valkey cache backend. You switch both on with one small file that you drop into your own site's files directory.

Create this file (from your oN.ftp shell, or over SFTP):

sites/example.com/files/development.services.yml

with these contents:

parameters:
  http.response.debug_cacheability_headers: true
  twig.config:
    debug: true
    auto_reload: true
    cache: true
services:
  cache.backend.null:
    class: Drupal\Core\Cache\NullBackendFactory

Here is what each part buys you, and what BOA does around it:

  • The services: block defines a "do nothing" cache backend. Just having this file present on a .dev. request tells BOA to load it and to route Drupal's render and dynamic page caches through that null backend instead of Valkey. So while you develop on the .dev. URL your edits aren't served from the cache layer, and you don't have to touch any cache configuration yourself.
  • twig.config: debug: true makes Drupal annotate the rendered HTML with the template file names and theme suggestions for every region and block, which is the whole point of Twig debugging.
  • Leave auto_reload: true and cache: true as shown. BOA's own guidance is to keep the Twig cache on: auto_reload already re-renders a template the moment its source changes, and turning the cache fully off just makes every page slower for no extra benefit.

One catch to remember. After you first add (or later remove) this file you must clear the site's caches once, or the .dev. URL can answer with an error 500 complaining about a missing cache.backend.null service. Clear caches either from the control panel with the Flush all caches task on the site, or from your shell:

drush @example.com cr

Then load https://www.dev.example.com and you'll see the Twig annotations in the page source.

Theme debugging on Drupal 7

Drupal 7 has no Twig, so the file above doesn't apply. The .dev. URL still relaxes caching and shows errors for you exactly the same way. For template-level debugging, Drupal 7 has its own switch you can flip with Drush from your shell:

drush @example.com vset theme_debug 1
drush @example.com cc all

Theme hook suggestions now appear as HTML comments around each rendered element. Turn it back off when you're done:

drush @example.com vset theme_debug 0
drush @example.com cc all

What you may edit, and what BOA rewrites

This is the part people trip on most often, so it's worth being clear. The site's PHP settings files are kept under your instance's own control, and they are reset for you on a schedule. Knowing which file to reach for saves a lot of head-scratching.

Leave these alone. BOA owns them and rewrites them:

  • sites/example.com/settings.php — regenerated every time the site is verified. It's the glue that wires the site to its database, its cache, and the shared BOA settings. Editing it is temporary at best and can break the site at worst.

Your first stop for a setting change: the site control file.

Most of the per-site knobs you'd once have reached into PHP for now live in a plain, commented INI file that is genuinely yours to edit from your shell or over SFTP:

sites/example.com/modules/boa_site_control.ini

BOA drops this file in for you the first time it tidies the site, group-writable so you can open it and change values. It's where you toggle things like which cache bins skip the cache backend (redis_exclude_bins), or turn the backend off site-wide (redis_cache_disable), without touching any PHP. These keys keep the redis_ prefix even on a server running Valkey — BOA uses a single redis_ namespace for both, so don't go looking for a valkey_ toggle. Open the file, read the comments, uncomment the line you want, and save. This is the supported, no-surprises place for a hosted site's overrides.

About local.settings.php and drushrc.php. These two PHP files also exist in your site directory, and BOA does not overwrite their contents — but it does reset their permissions back to read-only on every verify and again overnight, and they're owned by the site's system user rather than your oN.ftp shell user. So they are not files you can just open and edit the way you can the INI above. settings.php includes local.settings.php last, after everything else, which is what makes it the ultimate override point — but for a hosted site the safe way to get a lasting local.settings.php change in place is to ask your host: describe the override you need and open a support request. For the everyday settings, reach for boa_site_control.ini first — that's the one built for you to change.

There's a fuller tour of which file to reach for in Which file do I edit?.

Your actual code — the modules and themes under sites/all/ or sites/example.com/, and anything in a platform you built yourself — is entirely yours to edit in place. BOA only manages the settings wrappers; it doesn't rewrite your modules, themes, or libraries.

A comfortable loop

Putting it together, a typical session looks like this:

  1. Once, add a www.dev.example.com alias to the site so you have a preview URL.
  2. Once, if you want Twig debugging and a cache-free preview on Drupal 8+, drop in development.services.yml and run drush @example.com cr.
  3. Edit your theme or module code in place from your shell or over SFTP.
  4. Refresh https://www.dev.example.com to see the change with full errors and template hints. For a config or Twig change that isn't showing, drush @example.com cr (or cc all on Drupal 7) and refresh again.
  5. When you're happy, the live URL already has your code — it's the same site. Just take the development bits back off: remove development.services.yml (and clear caches), or set theme_debug 0 on Drupal 7.

If you ever want a throwaway copy to experiment on instead of your live site, clone the site first — see Cloning and migrating — and point a .dev. alias at the clone.

When something needs a change at the server level that these files and tasks can't reach — a PHP extension that isn't installed, a resource limit, anything outside your own instance — that's something your host does. Open a support request and describe what you need.

Related