Tutorial: Setting Up Drupal Umami Demo Site on freistilbox

This tutorial walks you through setting up the Drupal 11 Umami Food Magazine demo site on freistilbox. Umami is a demonstration installation profile included with Drupal core that showcases Drupal’s features through a fictional food magazine website.

This tutorial prioritizes getting you up and running quickly. We’ll use straightforward Git commands and simple workflows that work but aren’t necessarily production-ready. Future tutorials will show you how to improve and automate these processes. Think of this as your starting point in a learning journey.

What You’ll Learn

  • How to create a Drupal 11 project with Composer
  • How to adapt the project structure for freistilbox
  • How to configure the Boxfile for Drupal
  • How to create environment-specific settings
  • How to install Umami using Drush
  • How to deploy to freistilbox

Prerequisites

Before starting, make sure you have:

  • A freistilbox website (we’ll use site ID s5715 on cluster c61 as an example)
  • Your freistilbox website configured with:
    • Document root set to web
    • Deployment environment set to production
    • Deployment branch set to production
  • Composer installed on your local machine
  • Git installed
  • SSH access to your freistilbox site
  • Basic familiarity with command-line tools

Understanding the Umami Demo

The Umami installation profile (demo_umami) is included in Drupal core since version 8.6. It creates a complete demo website for a food magazine with:

  • Sample articles and recipes
  • Responsive Umami theme
  • Configured content types
  • Example media and images
  • Working navigation and taxonomy

Umami is for demonstration purposes only and not recommended as a foundation for production sites.

Step 1: Create a New Drupal 11 Project

Let’s start by creating a fresh Drupal 11 project using Composer’s recommended template:

cd ~
composer create-project drupal/recommended-project:^11 umami-freistilbox
cd umami-freistilbox

This creates a project with the following structure:

umami-freistilbox/
├── composer.json
├── composer.lock
├── vendor/
└── web/              # Document root
    ├── core/
    ├── modules/
    ├── themes/
    ├── sites/
    └── index.php

The recommended-project template puts the web files in a web/ subdirectory, which is not our default - we historically use docroot/. But we’ll configure freistilbox to use this directory, since this is configurable.

Step 2: Verify Your freistilbox Configuration

Make sure your freistilbox website is properly configured (these should already be set as mentioned in Prerequisites):

In the freistilbox Dashboard, verify:

  1. Document Root is set to web
  2. Deployment Environment is set to production
  3. Deployment Branch is set to production

These settings ensure that:

  • freistilbox knows where to find your web files (in the web/ directory)
  • The correct environment-specific settings file will be used (settings.production.php)
  • Deployments are done from the production branch

Step 3: Add Drush for Command-Line Administration

Drush is essential for installing Drupal and managing it from the command line:

composer require drush/drush

This installs Drush into vendor/bin/drush.

Step 4: Create the Boxfile

The Boxfile tells freistilbox how to handle your application. Create a file named Boxfile (case-sensitive, capital B) in the project root:

touch Boxfile

Edit the Boxfile with the following content:

version: 2.0

shared_folders:
  - web/sites/default/files

env_specific_files:
  web/sites/default/settings.php:
    production: settings.production.php
  web/.htaccess:
    production: .htaccess.production

What this does:

  • Tells freistilbox to use version 2.0 of the Boxfile format
  • Designates web/sites/default/files as a shared folder (for uploaded files)
  • Sets up environment-specific settings for production
  • The key (e.g., web/sites/default/settings.php) is the symlink that freistilbox will create
  • The value (e.g., settings.production.php) is the filename in the same directory as the symlink

Since your website’s deployment environment is set to production in the freistilbox Dashboard, freistilbox will automatically create symlinks pointing to the files defined under production: in the env_specific_files section.

Step 5: Create Production Settings File

Drupal needs specific settings for the production environment. This file needs to be in the same directory as where the symlink will point.

Production Settings

Create web/sites/default/settings.production.php:

<?php
/**
 * @file
 * Drupal production environment settings.
 */

// Include the default settings.
if (file_exists(__DIR__ . '/default.settings.php')) {
  require_once __DIR__ . '/default.settings.php';
}

// Hash salt for security.
// Generate your own with: openssl rand -base64 32
$settings['hash_salt'] = 'YOUR_GENERATED_HASH_SALT_HERE';

// Configure the private files directory (relative to web/).
$settings['file_private_path'] = '../private';

// Configuration sync directory.
$settings['config_sync_directory'] = '../private/sync';

// Trusted host patterns.
// Add your production domain(s) here.
$settings['trusted_host_patterns'] = [
  '^umami\.c61\.freistilbox\.net$',
  '^www\.example\.com$',
  '^example\.com$',
];

// Include freistilbox configuration snippets.
if (file_exists('../config/drupal/settings-d8-site.php')) {
  require_once '../config/drupal/settings-d8-site.php';
}

if (file_exists('../config/drupal/settings-d8-db5840.php')) {
  require_once '../config/drupal/settings-d8-db5840.php';
}

// Override Twig storage to use system temp directory for Drupal 11 compatibility.
$settings['php_storage']['twig'] = [
  'class' => '\Drupal\Component\PhpStorage\FileStorage',
  'directory' => sys_get_temp_dir() . '/php',
];

Important Notes:

  • The private path ../private is relative to the web/ directory - freistilbox provides this automatically
  • Update the trusted host patterns with your actual domain names
  • The configuration sync directory is ../private/sync - using the shared private/ directory ensures it’s writable during deployment. In a future tutorial, we’ll change this to use ../configuration/sync from Git for better configuration management, but for simplicity we’re using shared storage for now.
  • Note that ../config/ is freistilbox’s own configuration directory (read-only), different from Drupal’s config sync directory
  • freistilbox provides two separate configuration snippets:
    • settings-d8-site.php for site configuration (temp directory, etc.)
    • settings-d8-db5840.php for database connection (your database name may differ)
  • These paths are relative to web/sites/default/ where this file lives
  • The Twig storage override is required for Drupal 11 compatibility on freistilbox

Step 6: Create Production .htaccess File

Drupal includes a .htaccess file for Apache configuration. We’ll create a production-specific variant.

cp web/.htaccess web/.htaccess.production

This can be identical to the default for now. Later, you might want to add production-specific rules (like IP restrictions or custom redirects).

In the Boxfile, the value .htaccess.production is relative to the directory where the symlink web/.htaccess will be created (i.e., the web/ directory).

Update .gitignore

Since .htaccess and settings.php will be generated by freistilbox as symlinks, we should exclude them from Git.

Add to .gitignore:

# Environment-specific files (managed by freistilbox)
web/sites/default/settings.php
web/.htaccess

# freistilbox shared storage paths
web/sites/default/files

# Other freistilbox reserved paths
/private/
/config/
/tmp/

Step 7: Initialize Git Repository

Now let’s set up version control:

cd ~/umami-freistilbox

# Create scripts directory for helper scripts
mkdir -p scripts

# Initialize git repository
git init

# Add all files
git add .

# Make initial commit
git commit -m "Initial Drupal 11 Umami project for freistilbox"

The default .gitignore excludes vendor/ and other built files. This is correct for your development repository. We’ll include them when deploying to freistilbox.

Step 8: Note on Configuration Directory

The production settings file we created in Step 5 is configured to use ../private/sync for the configuration sync directory:

$settings['config_sync_directory'] = '../private/sync';

Why use shared storage for config sync?

  • For this tutorial, we’re using the shared private/ directory to ensure the sync directory is writable during deployment and installation
  • This simplifies the initial setup and prevents permission issues
  • In a future tutorial, we’ll show how to migrate to using ../configuration/sync from Git for proper configuration management workflow
  • The private/ directory is in freistilbox’s shared storage, automatically created and persisted across deployments

We’ll export the actual Drupal configuration after installing the site on freistilbox in Step 11.

Step 9: Set Up Git Remote for Deployment

We’ll set up a Git remote to push directly to freistilbox:

cd ~/umami-freistilbox

# Add freistilbox as a remote for production
git remote add production s5715@repo.freistilbox.net:s5715

Now you can push to freistilbox like any other Git remote!

Step 10: Deploy to freistilbox

Now let’s deploy your site to freistilbox. We’ll use a temporary deployment branch to keep the vendor/ directory out of your main development branch.

Deploy to Production 

# Create a temporary deployment branch
git checkout -b deployment

# Build production dependencies
composer install --no-dev

# Add vendor directory (forced, ignoring .gitignore)
git add -f vendor/

# Commit everything
git commit -m "deployment build"

# Push to freistilbox production branch
git push production deployment:production

# Return to main branch
git checkout main

# Delete the temporary deployment branch
git branch -D deployment

What’s happening:

  • We create a temporary branch called deployment
  • composer install --no-dev installs only production dependencies
  • git add -f vendor/ forces Git to include vendor/ despite .gitignore
  • We commit and push this branch to freistilbox
  • After deployment, we delete the temporary branch
  • Your main branch stays clean without vendor/

This keeps your main development branch clean while still getting vendor/ to freistilbox. It’s simple, uses basic Git commands, and works well for manual deployments. Later tutorials will show you how to automate this with CI/CD.

Step 11: Install Drupal on freistilbox

After your first deployment, you need to install Drupal on freistilbox. SSH into your shell box and run the installation:

# SSH into your freistilbox shell box
ssh s5715@c61s.freistilbox.net

# Install Drupal with Umami profile using the simpler command format
current/vendor/bin/drush -r current/web site:install demo_umami \
  --site-name="Umami Food Magazine" \
  --account-name=admin \
  --account-pass=CHOOSE_A_SECURE_PASSWORD \
  --yes

# Exit SSH
exit

Now visit your site at https://s5715.c61.freistilbox.net - you should see the Umami Food Magazine!

During installation, you may see warnings about the configuration sync directory. This is expected because the sync directory (../private/sync) is in shared storage and initially empty. The installation will complete successfully, and the directory will be created automatically.

Step 12: Post-Deployment Tasks

After deploying changes to freistilbox, you typically need to run these commands via SSH:

# SSH into freistilbox
ssh s5715@c61s.freistilbox.net

# Navigate to web directory
cd current/web

# Run database updates (if any)
../vendor/bin/drush updatedb --yes

# Import configuration changes
../vendor/bin/drush config:import --yes

# Clear all caches
../vendor/bin/drush cache:rebuild

# Exit
exit

Understanding the Adaptations

Let’s review the key adaptations we made for freistilbox:

1. Document Root Configuration

  • Used the default web/ directory from Drupal’s composer template
  • Configured freistilbox Dashboard to use web/ as document root instead of docroot/

2. Boxfile Configuration

  • Defined web/sites/default/files as shared folder
  • Set up environment-specific settings file for production
  • Environment-specific files live in the same directory as the symlink target

3. Settings Files

  • Created production settings file in web/sites/default/
  • Used relative path ../private for private files directory (freistilbox provides this)
  • Included freistilbox configuration snippets for site and database settings
  • Configured configuration/sync directory for configuration management

4. Deployment Process

  • Set up Git remote pointing to freistilbox
  • Use temporary deployment branch to keep main branch clean
  • Build with composer install --no-dev on deployment branch
  • Include vendor/ directory on deployment branch
  • Push deployment branch to production branch on freistilbox
  • Delete deployment branch after each deployment
  • Run post-deployment tasks manually via SSH

5. Configuration Management

  • Exported Drupal configuration to configuration/sync/ directory
  • Import configuration after deployment for consistency

Troubleshooting

“Trusted host pattern not configured”

Add your domain to the trusted_host_patterns array in web/sites/default/settings.production.php.

Files not uploading

Check that web/sites/default/files is listed in the Boxfile’s shared_folders and has proper permissions on freistilbox.

White screen after deployment

Common causes:

  • Missing database updates (run drush updatedb)
  • Missing vendor directory (ensure composer install --no-dev ran and vendor/ was pushed)
  • PHP errors (check error logs via SSH: ssh s5715@c61s.freistilbox.net "tail -f logs/2025/10/error.*.log")

Wrong settings file being used

Check which environment your freistilbox instance is configured for in the Dashboard. The symlink web/sites/default/settings.php should point to the correct environment-specific file.

Next Steps

Now that you have Umami running on freistilbox, you can:

  1. Customize the theme: The Umami theme is in web/core/profiles/demo_umami/themes/umami/ - see Drupal theming docs
  2. Add custom modules: Create in web/modules/custom/ - see Drupal module development
  3. Configure domains: Add your custom domain in the freistilbox Dashboard
  4. Set up SSL: freistilbox provides free Let’s Encrypt SSL certificates
  5. Configure caching: Adjust Drupal’s performance settings for production
  6. Automate deployments: Consider setting up CI/CD for automated deployments

Important Reminders

  • Umami is a demo: It’s great for learning and showcasing, but not recommended for building real production sites
  • Keep it updated: Regularly update Drupal core and contrib modules for security
  • Back up regularly: Use freistilbox’s backup features or Drush to export databases
  • Clean deployment workflow: Use the temporary deployment branch to keep vendor/ out of your main branch

Summary

You’ve successfully:

  • Created a Drupal 11 project with Composer using the default structure
  • Configured freistilbox to use the web/ directory as document root
  • Set up the Boxfile with shared folders and environment-specific settings
  • Created production settings file with freistilbox configuration snippets
  • Configured Git remote for deployment
  • Deployed and installed the Umami demo site on freistilbox
  • Exported the site configuration to track in Git
  • Set up a workflow for future updates with post-deployment tasks

The Umami Food Magazine is now running on freistilbox’s distributed infrastructure, with proper shared folders, environment-specific configuration, and a simple Git-based deployment process.

Happy Drupaling! 🎉