Deploying Backdrop CMS

Backdrop CMS is a free, open-source content management system that helps you build modern, comprehensive websites on a reasonable budget. Forked from Drupal 7, Backdrop preserves the ease of use and extensive ecosystem that made Drupal 7 the most popular version of Drupal while maintaining active development and security updates.

With over 1,000 GitHub stars and an active community, Backdrop CMS powers more than 3,600 websites worldwide—from non-profits and educational institutions to small businesses and personal blogs. It offers a familiar interface for Drupal users while providing a straightforward upgrade path from legacy Drupal 7 sites.

Easy to Use

Non-technical users can create and manage content without coding

Fast Performance

Optimized to serve pages quickly, even on shared hosting

Drupal Compatible

Easy upgrade path from Drupal 7 with 1300+ add-ons

Actively Maintained

Regular security updates and predictable release cycles

Key Features

Backdrop CMS provides comprehensive content management capabilities:

Feature	Description
Content Types	Create custom content types with flexible fields
Layout System	Visual drag-and-drop page layouts
Views	Build dynamic content displays and listings
User Management	Roles, permissions, and user authentication
Multilingual	Built-in support for multiple languages
SEO Tools	Clean URLs, meta tags, and search optimization
Media Management	Upload and manage images, files, and media
Extensible	1,300+ contributed modules and themes
API Access	RESTful web services for headless CMS usage
Configuration Management	Export/import site configuration

System Requirements

Backdrop CMS requires:

Component	Requirement
PHP	7.1 or higher (8.x recommended)
Database	MySQL 5.5+ or MariaDB 5.5+
Web Server	Apache (recommended) or Nginx
Disk Space	15 MB minimum, 60+ MB recommended

Prerequisites

Before deploying Backdrop CMS on Klutch.sh, ensure you have:

• A Klutch.sh account with an active project
• A GitHub repository for your deployment
• A MySQL/MariaDB database (can be deployed on Klutch.sh - see MySQL guide or MariaDB guide)

Project Structure

Set up your Backdrop CMS deployment repository:

• Directorybackdrop-cms/

  • Dockerfile
  • docker-compose.yml (local development only)
  • .env.example
  • README.md

Deployment Configuration

Dockerfile

Backdrop CMS has an official Docker image. Create a Dockerfile to use it:

Dockerfile

FROM backdrop:latest

# The official image is based on PHP 8.3 with Apache
# and includes all required PHP extensions

# Backdrop files are in /var/www/html
WORKDIR /var/www/html

# The sites and files directories need to be writable
# These are handled by the base image

# Apache runs on port 80
EXPOSE 80

Alternative: Custom Build with Specific Version

For more control over the version and configuration:

Dockerfile

FROM php:8.3-apache

# Enable Apache mod_rewrite for clean URLs
RUN a2enmod rewrite

# Install required PHP extensions
RUN apt-get update && apt-get install -y --no-install-recommends \
    libzip-dev \
    libonig-dev \
    libpng-dev \
    libjpeg-dev \
    libpq-dev \
    && rm -rf /var/lib/apt/lists/* \
    && docker-php-ext-configure gd --with-jpeg=/usr \
    && docker-php-ext-install gd mbstring pdo pdo_mysql pdo_pgsql zip

WORKDIR /var/www/html

# Download and extract Backdrop CMS
ENV BACKDROP_VERSION=1.32.1

RUN curl -fSL "https://github.com/backdrop/backdrop/releases/download/${BACKDROP_VERSION}/backdrop.zip" -o backdrop.zip \
    && unzip backdrop.zip \
    && mv backdrop/* . \
    && mv backdrop/.htaccess . \
    && rm -rf backdrop backdrop.zip \
    && chown -R www-data:www-data sites files

# Copy custom entrypoint for database configuration
COPY docker-entrypoint.sh /entrypoint.sh
RUN chmod +x /entrypoint.sh

ENTRYPOINT ["/entrypoint.sh"]
CMD ["apache2-foreground"]

EXPOSE 80

Docker Entrypoint Script

Create a docker-entrypoint.sh to configure database settings:

docker-entrypoint.sh

#!/bin/bash
set -e

if [[ "$1" == apache2* ]] || [ "$1" == php-fpm ]; then
  # Check for required database configuration
  if [ -z "$BACKDROP_DB_HOST" ]; then
    echo >&2 'error: missing BACKDROP_DB_HOST environment variable'
    exit 1
  fi

  # Set defaults
  : ${BACKDROP_DB_USER:=backdrop}
  : ${BACKDROP_DB_NAME:=backdrop}
  : ${BACKDROP_DB_PORT:=3306}
  : ${BACKDROP_DB_DRIVER:=mysql}

  if [ -z "$BACKDROP_DB_PASSWORD" ]; then
    echo >&2 'error: missing required BACKDROP_DB_PASSWORD environment variable'
    exit 1
  fi

  # Construct BACKDROP_SETTINGS JSON and pass to Apache
  export BACKDROP_SETTINGS="{\"databases\":{\"default\":{\"default\":{\"host\":\"$BACKDROP_DB_HOST\",\"port\":$BACKDROP_DB_PORT,\"username\":\"$BACKDROP_DB_USER\",\"password\":\"$BACKDROP_DB_PASSWORD\",\"database\":\"$BACKDROP_DB_NAME\",\"driver\":\"$BACKDROP_DB_DRIVER\"}}}}"

  if [[ "$1" == apache2* ]]; then
    echo "PassEnv BACKDROP_SETTINGS" > /etc/apache2/conf-enabled/backdrop.conf
  fi
fi

exec "$@"

Environment Variables

Backdrop CMS Docker image uses the following environment variables:

Required Variables

Variable	Description	Example
BACKDROP_DB_HOST	MySQL/MariaDB hostname	mysql-hostname
BACKDROP_DB_PASSWORD	Database password	your-secure-password

Optional Variables

Variable	Description	Default
BACKDROP_DB_USER	Database username	backdrop
BACKDROP_DB_NAME	Database name	backdrop
BACKDROP_DB_PORT	Database port	3306
BACKDROP_DB_DRIVER	Database driver	mysql

Local Development with Docker Compose

Test your Backdrop CMS setup locally:

docker-compose.yml

services:
  backdrop:
    image: backdrop:latest
    container_name: backdrop
    ports:
      - "8080:80"
    environment:
      BACKDROP_DB_HOST: mysql
      BACKDROP_DB_USER: backdrop
      BACKDROP_DB_PASSWORD: backdrop
      BACKDROP_DB_NAME: backdrop
    volumes:
      - backdrop_files:/var/www/html/files
      - backdrop_sites:/var/www/html/sites
    depends_on:
      mysql:
        condition: service_healthy
    restart: unless-stopped

  mysql:
    image: mysql:8.0
    container_name: backdrop-db
    environment:
      MYSQL_DATABASE: backdrop
      MYSQL_USER: backdrop
      MYSQL_PASSWORD: backdrop
      MYSQL_ALLOW_EMPTY_PASSWORD: 'yes'
    volumes:
      - mysql_data:/var/lib/mysql
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
      interval: 5s
      timeout: 5s
      retries: 5
    restart: unless-stopped

volumes:
  backdrop_files:
  backdrop_sites:
  mysql_data:

Tip

Run docker compose up -d to start Backdrop CMS locally. Access the installation wizard at http://localhost:8080. Use the database credentials: user backdrop, password backdrop, database backdrop.

Deploying to Klutch.sh

1. Deploy a MySQL database

   1. First, deploy a MySQL or MariaDB database on Klutch.sh
   2. See our MySQL deployment guide or MariaDB deployment guide for detailed instructions
   3. Create a database named backdrop
   4. Create a user with full privileges on the backdrop database

   CREATE DATABASE backdrop CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
   CREATE USER 'backdrop'@'%' IDENTIFIED BY 'your-secure-password';
   GRANT ALL PRIVILEGES ON backdrop.* TO 'backdrop'@'%';
   FLUSH PRIVILEGES;

2. Push your repository to GitHub

   1. Create a new GitHub repository
   2. Add the Dockerfile and entrypoint script to your repository

   git init
   git add .
   git commit -m "Initial Backdrop CMS configuration"
   git remote add origin https://github.com/yourusername/backdrop-cms.git
   git push -u origin main

3. Create a new app on Klutch.sh

   1. Navigate to your Klutch.sh dashboard at klutch.sh/app
   2. Select your project or create a new one
   3. Click Create App and connect your GitHub repository
   4. Klutch.sh will automatically detect your Dockerfile

4. Configure environment variables

   1. In your app settings, add the required environment variables

   Variable	Value
   BACKDROP_DB_HOST	Your MySQL hostname (internal Klutch.sh hostname)
   BACKDROP_DB_USER	backdrop
   BACKDROP_DB_PASSWORD	Your secure database password
   BACKDROP_DB_NAME	backdrop
   BACKDROP_DB_PORT	3306

5. Configure the internal port

   1. Set the internal port to 80
   2. Select HTTP as the traffic type

6. Set up persistent storage

   1. Add persistent volumes for Backdrop’s writable directories

   Mount Path	Size
   /var/www/html/files	10 GB
   /var/www/html/sites	5 GB

   Note

   The files directory stores uploaded content (images, documents). The sites directory contains configuration and can be shared if running multisite.

7. Deploy your application

   1. Click Deploy to build and launch Backdrop CMS
   2. Monitor the build logs for any issues
   3. Once deployed, your app will be available at https://your-app.klutch.sh

Initial Setup

After deployment, complete the Backdrop CMS installation:

1. Access the installation wizard

   1. Navigate to https://your-app.klutch.sh
   2. You’ll be redirected to the installation wizard

2. Choose installation profile

   1. Select Standard for a typical site with common features enabled
   2. Or choose Minimal for a bare installation

3. Verify requirements

   1. The installer will check system requirements
   2. All requirements should pass with the Docker configuration

4. Database configuration

   1. The database should be auto-configured via environment variables
   2. If prompted, enter your database credentials:

   Field	Value
   Database name	backdrop
   Database username	backdrop
   Database password	Your password
   Host	Your MySQL hostname
   Port	3306

5. Configure site information

   1. Enter your site name
   2. Create your admin account with a strong password
   3. Set your site email address
   4. Configure regional settings (country, timezone)

6. Complete installation

   1. Click Save and continue
   2. The installer will set up your site
   3. You’ll be redirected to your new Backdrop site

Managing Content

Backdrop CMS provides intuitive content management:

Creating Content Types

1. Add a new content type

   1. Navigate to Structure → Content types
   2. Click Add content type
   3. Enter name and description
   4. Configure submission settings

2. Add fields to your content type

   1. Click Manage fields on your content type
   2. Add fields (text, image, file, reference, etc.)
   3. Configure field settings and validation

Creating Content

1. Create new content

   1. Navigate to Content → Add content
   2. Select the content type
   3. Fill in the fields
   4. Set publishing options
   5. Click Save

Layout Management

Backdrop’s layout system allows visual page building:

1. Access layout administration

   1. Navigate to Structure → Layouts
   2. View existing layouts or add new ones

2. Edit a layout

   1. Click Configure on a layout
   2. Drag and drop blocks into regions
   3. Configure block settings
   4. Set visibility conditions
   5. Save the layout

Installing Modules and Themes

Backdrop has a built-in installer for add-ons:

1. Install from the admin interface

   1. Navigate to Functionality (for modules) or Appearance (for themes)
   2. Click Install new module/theme
   3. Enter the project URL or upload a zip file
   4. Click Install

2. Enable the module/theme

   1. After installation, enable the module in Functionality
   2. Or set the theme as default in Appearance

Tip

Browse available add-ons at backdropcms.org/add-ons. Backdrop is compatible with many Drupal 7 modules with minimal modifications.

User Management

Configure users, roles, and permissions:

1. Create user roles

   1. Navigate to Configuration → People → Roles
   2. Add roles like “Editor”, “Contributor”, etc.

2. Configure permissions

   1. Navigate to Configuration → People → Permissions
   2. Check permissions for each role
   3. Save permissions

3. Add users

   1. Navigate to People → Add user
   2. Enter user details and assign roles

Configuration Management

Backdrop’s configuration management allows you to export and import site settings:

1. Export configuration

   1. Navigate to Configuration → Development → Configuration management
   2. Click Export to download a full configuration export
   3. Or use Single export for specific items

2. Import configuration

   1. Navigate to Configuration management
   2. Use Import to upload configuration
   3. Review and confirm changes

Note

Configuration files are stored in the sites/default/files/config_* directories. Include these in your persistent storage for backup.

Performance Optimization

Optimize your Backdrop site:

1. Enable caching

   1. Navigate to Configuration → Development → Performance
   2. Enable Cache pages for anonymous users
   3. Enable Aggregate and compress CSS files
   4. Enable Aggregate JavaScript files

2. Configure cache lifetime

   1. Set Minimum cache lifetime as needed
   2. Set Expiration of cached pages for external caches

Security Best Practices

Update Regularly

Keep Backdrop core and modules updated for security patches

Strong Passwords

Use strong passwords for admin and database accounts

HTTPS Only

Klutch.sh provides automatic SSL certificates

Limit Permissions

Grant only necessary permissions to each role

Security Module

Enable Backdrop’s security features:

1. Configure text formats

   1. Navigate to Configuration → Content authoring → Text formats
   2. Review allowed HTML tags for each format
   3. Enable appropriate filters

2. Review user permissions

   1. Audit permissions regularly
   2. Remove unnecessary permissions from roles

Backup and Recovery

Database Backup

# Export database
mysqldump -u backdrop -p backdrop > backdrop_backup.sql

# Import database
mysql -u backdrop -p backdrop < backdrop_backup.sql

Files Backup

The persistent volumes contain:

• /var/www/html/files - Uploaded content
• /var/www/html/sites - Configuration and site-specific data

Upgrading from Drupal 7

Backdrop provides a built-in upgrade path from Drupal 7:

1. Prepare your Drupal 7 site

   1. Update Drupal 7 to the latest version
   2. Disable and uninstall modules not available in Backdrop
   3. Back up your database and files

2. Perform the upgrade

   1. Install a fresh Backdrop instance
   2. Copy your Drupal 7 database to Backdrop
   3. Copy your files directory
   4. Run update.php to perform database migrations

See the Backdrop upgrade documentation for detailed instructions.

Troubleshooting

Common issues and solutions:

Issue	Cause	Solution
White screen	PHP error	Check logs, enable error reporting
Database connection failed	Wrong credentials	Verify BACKDROP_DB_* environment variables
Clean URLs not working	mod_rewrite disabled	Ensure Apache mod_rewrite is enabled
Permission denied	File permissions	Check ownership of sites and files directories
Modules not installing	Disk space	Check persistent volume size

Checking Logs

Monitor logs through the Klutch.sh dashboard:

1. View application logs

   1. Navigate to your app in the Klutch.sh dashboard
   2. Check deployment and runtime logs
   3. Look for PHP and Apache error messages

Status Report

Check Backdrop’s status report:

1. View status report

   1. Navigate to Reports → Status report
   2. Review any warnings or errors
   3. Follow recommended actions

Additional Resources

• Official Backdrop Documentation
• Backdrop CMS GitHub Repository
• Backdrop Add-ons (Modules & Themes)
• Backdrop Forum
• Backdrop API Documentation
• Try Backdrop CMS Demo
• Drupal 7 to Backdrop Migration Guide
• Backdrop Docker Repository