README

Paragon is a Drupal distribution focused on providing a clean starting point for site builds with just the right amount of baked in configuration.This allows developers to focus on building custom functionality, rather than recreating the same standard set of baseline features they’ve built 100 times before.

The intent of this distribution is to create a Drupal install that will be treated as an artifact and maintained independently of this project after the initial installation. As such, rather than making this an official install profile, Paragon is instead managed as a Composer template that heavily leverages drupal/core-composer-scaffold and also includes exported configuration that can be used to install the site.

Prerequisites

Download DDEV if it is not already installed.
Access to Elevated Third Github organization, Paragon-base repository and SSH key setup.
You must be using Composer 2.

Setup instructions

Step #1: Clone repository

Run the following command: composer create-project elevatedthird/paragon-base [install_directory_name] which will clone down the composer template and create all necessary files.
You will prompted to select a hosting environment for your project. Select 'custom' if you don't want platform specific files. You can set up hosting requirements later by running composer setup-platform

Step #2: Project setup

Rename the the app in the .ddev/config.yml file
ddev start
ddev composer install
ddev composer npm-install

Step #3: Install Drupal

Install the site: ddev drush si --existing-config --site-name=[SITE_NAME] --account-name=root --account-pass=[PASSWORD] -vv -y
Once install completes, remove the automatically generated database connection details that have most likely been appended to the bottom of settings.php.
Install starter components: ddev drush propel:init
Build the theme: ddev vite:build

Step #4: Set up Solr Search

ddev drush pm:enable search_api_solr_admin

This module is ignored in settings.php

Create a new Solr server connection in the UI
Follow the ddev-solr steps to connect to Solr
Upload the config set to Solr and create the collection. ddev drush --numShards=1 search-api-solr:upload-configset [YOUR_SERVER_NAME]

Essential DDEV commands

ddev xdebug on
ddev xdebug off
ddev vite
ddev vite:build

E3 Github Workflows

By default, all Paragon projects have Github Actions enabled. To disable, rename the .github/workflows/main.yml to main.disable

Ensure you have invited hosting@elevatedthird.com to your project.
Set up the .env file located in the project root. These variables will be used as settings for the Github Workflows.
If your site is on Pantheon, you will need to uncomment and fill out the PANTHEON_SITE var.
If you are NOT using kinetic, change the THEME_NAME variable to the name of the active theme's folder. Also, change the paths to the theme in the build-theme and npm-install scripts in composer.json

Specific Platform Instructions

Acquia

Ensure you have a hooks/dev/post-code-update/drush-deploy.sh
Ensure that the code below is present in the settings.php.

if (isset($_ENV['AH_SITE_ENVIRONMENT'])) {
  if (file_exists($app_root . '/' . $site_path . '/settings.acquia.php')) {
    include $app_root . '/' . $site_path . '/settings.acquia.php';
  }
}

Pantheon

Ensure you change the docroot folder name to web
Change docroot to web in your composer.json file
Ensure that the code below is present in the settings.php.

if(isset($_ENV['PANTHEON_ENVIRONMENT'])) {
  if (file_exists($app_root . '/' . $site_path . '/settings.pantheon.php')) {
    include $app_root . '/' . $site_path . '/settings.pantheon.php';
  }
}

Platform

Ensure your .platform.app.yaml deploy hook looks like this

  deploy: |
    set -e
    php ./drush/platformsh_generate_drush_yml.php
    cd docroot
    drush deploy

Ensure that the code below is present in the settings.php.

if (isset($_ENV['PLATFORM_PROJECT'])) {
  if (file_exists($app_root . '/' . $site_path . '/settings.platformsh.php')) {
    include $app_root . '/' . $site_path . '/settings.platformsh.php';
  }
}

Tugboat Integration

By default, Paragon creates a .tugboat folder containing configuration related to Tugboat QA. You must set up a tugboat project and connect the Github repo to it.

Claude Code

Paragon ships with a Claude Code setup designed to run inside the DDEV web container. The following files drive the integration.

CLAUDE.md

A CLAUDE.md template lives in the project root. It contains project-specific instructions that Claude reads at the start of every session — things like the site name, key modules, hosting environment, and known gotchas. Fill it out before using Claude Code on the project. Claude will refuse to proceed until the template status is marked complete.

Permission rules (`.claude/settings.json`)

The project .claude/settings.json defines three tiers of permissions:

Deny — Claude is blocked from running these automatically and cannot ask for approval either. Covers destructive or sensitive operations:

Reading .env, settings.php, settings.local.php, certificates, and key files
drush sql-drop, drush site-install, and any Drush remote aliases (@prod, etc.)
rm -rf, git push --force, git merge, git rebase
Acquia CLI (acli) commands and .acquia files

Ask — Claude must prompt for approval before running:

composer require / update / remove
git commit and git push

Allow — Claude can run these without prompting:

Safe Drush read/cache/config commands (drush status, drush cr, drush config:*, drush pm:list, drush updb, drush watchdog:show, etc.)
Code quality tools: phpcs, phpstan, phpunit

Mounting your host `~/.claude` into the container

docker-compose.claude-home.yaml provides commented-out volume definitions that shim your host machine's Claude config into the DDEV web container. This lets Claude inside the container share your global commands, skills, and plugins without duplicating them. Two options are available — uncomment one:

# Option 1: full ~/.claude (settings, history, sessions, commands, plugins)
- ${HOME}/.claude:/root/.claude:ro

# Option 2: granular — commands and plugins only
- ${HOME}/.claude/commands:/root/.claude/commands:ro
- ${HOME}/.claude/plugins:/root/.claude/plugins:ro

The volume is mounted read-only so the container cannot modify your host Claude config.

Per-project `.claude.json` persistence

config.claude-code.yaml runs a post-start hook that creates a .ddev/claude-code/.claude.json file (if it doesn't exist) and symlinks it to ~/.claude.json inside the container. This keeps any project-level Claude state (conversation history, approvals) in the repo's .ddev folder rather than lost on container rebuild.

elevatedthird / paragon-base

Maintainers

Package info

Statistics

Security

README

Prerequisites

Setup instructions

Step #1: Clone repository

Step #2: Project setup

Step #3: Install Drupal

Step #4: Set up Solr Search

Essential DDEV commands

E3 Github Workflows

Specific Platform Instructions

Acquia

Pantheon

Platform

Tugboat Integration

Claude Code

CLAUDE.md

Permission rules (`.claude/settings.json`)

Mounting your host `~/.claude` into the container

Per-project `.claude.json` persistence

Related Projects

elevatedthird / paragon-base

Maintainers

Package info

Statistics

Security

README

Prerequisites

Setup instructions

Step #1: Clone repository

Step #2: Project setup

Step #3: Install Drupal

Step #4: Set up Solr Search

Essential DDEV commands

E3 Github Workflows

Specific Platform Instructions

Acquia

Pantheon

Platform

Tugboat Integration

Claude Code

CLAUDE.md

Permission rules (.claude/settings.json)

Mounting your host ~/.claude into the container

Per-project .claude.json persistence

Related Projects

Permission rules (`.claude/settings.json`)

Mounting your host `~/.claude` into the container

Per-project `.claude.json` persistence