Drupal guide

# Get ready

It's assumed you've already created a new app and chose Drupal in the software template. If not: You can do so in the fortrabbit dashboard. You should have a local PHP development environment running on your local machine. Drupal has good backward compatibility and this guide should work for Drupal 10 and 11. We recommend following the official Drupal installation guide↗ to install Drupal locally first. Here is an idea how to do it with Composer:

# Create a new Drupal project with Composer
composer create-project drupal/recommended-project my-drupal-site

# Navigate to the project directory
cd my-drupal-site

# Install Drupal via Composer (alternative method)
composer install

We recommend to use DDEV for local development. See their Drupal quick start↗.

# Root path

If Drupal was chosen or detected when creating the environment in the dashboard, 'web' was pre-selected as the root path. You can configure the root path in the dashboard.

# MySQL configuration

If Drupal was chosen or detected, required environment variables for the MySQL connection will be pre-populated.

# Deployment

Drupal supports Git and Composer workflows. Deploy via GitHub using our GitHub integration via git push. SSH/SFTP code access is also available.

# Git ignores

At the time of writing, it appears that Drupal does not ship with a standard .gitignore file. It's suggested to create such a file on the root directory of the project, matching your requirements.

• drupal.org/project/drupal_cms/issues/3500134↗ - Issue
• github.com/github/gitignore/blob/main/Drupal.gitignore↗ - Example

# Git deployment workflow

1. Set up your local Drupal project with Git
2. Deploy to GitHub
3. Install the fortrabbit GitHub App
4. Connect your GitHub repository to your fortrabbit app environment
5. Push to deploy automatically

The build commands will automatically run composer install during deployment when using our Drupal software template.

# Initial deployment steps

1. Create your Drupal project locally
2. Initialize Git and make your initial commit
3. Push your code to your GitHub repository
4. Deploy to fortrabbit via GitHub integration
5. Install Drupal via SSH with vendor/bin/drush site:install, or import an existing database
6. Export the configuration and commit it, see Drush below

# Drush

Drush is the Drupal command line tool. Require it with Composer, so it ships with every deployment:

composer require drush/drush

Call it directly via SSH, not through the PHP interpreter: vendor/bin/drush is a shell script.

ssh {{app-env-id}}@ssh.{{region}}.frbit.app
vendor/bin/drush status

# Drush deploy

drush deploy runs database updates, imports the configuration and rebuilds caches. The Drupal software template sets it as a post deploy command. It is skipped while Drush is missing or the site is not installed yet, so the first deployment of a fresh environment does not fail:

if vendor/bin/drush status --field=bootstrap 2>/dev/null | grep -q Successful; then vendor/bin/drush deploy; else echo 'No drush or no installed Drupal site, skipping drush deploy'; fi

drush deploy imports the configuration from the sync directory. It refuses an empty sync directory, and the deployment fails. Export the configuration locally and commit it:

vendor/bin/drush config:export
git add config/sync

# Files and uploads

Drupal stores uploaded files in the web/sites/default/files directory by default. The software template excludes that directory from deployments, so uploads persist when new code is deployed.

# Using rsync for file management

You can use rsync to sync files between your local development and fortrabbit:

# Download files from fortrabbit to local
rsync -av {{app-env-id}}@ssh.{{region}}.frbit.app:web/sites/default/files/ ./web/sites/default/files/

# Upload files from local to fortrabbit
rsync -av ./web/sites/default/files/ {{app-env-id}}@ssh.{{region}}.frbit.app:web/sites/default/files/

# Environment variables

When Drupal is detected or chosen, important environment variables for connecting to the database should be pre-configured. Set these environment variables in your fortrabbit dashboard:

# Additional ENV vars

• DRUPAL_HASH_SALT: the hash salt, set to a random value by the software template
• Other custom variables as needed for your modules

# Logs

Check your Drupal logs via the admin interface at /admin/reports/dblog or access system logs in the fortrabbit dashboard.

# Manual database settings

Drupal reads the database connection from web/sites/default/settings.php. The software template sets the DB_* environment variables. Read them in settings.php:

if (getenv('DB_HOST')) {
  $databases['default']['default'] = [
    'driver' => 'mysql',
    'database' => getenv('DB_DATABASE'),
    'username' => getenv('DB_USERNAME'),
    'password' => getenv('DB_PASSWORD'),
    'host' => getenv('DB_HOST'),
    'port' => getenv('DB_PORT') ?: '3306',
    'prefix' => '',
    'collation' => 'utf8mb4_general_ci',
  ];
  $settings['hash_salt'] = getenv('DRUPAL_HASH_SALT');
  $settings['config_sync_directory'] = '../config/sync';
}

For your local development setup, you can create a settings.local.php file with your local database credentials.