Drupal 11 in Docker. Enterprise CMS, pinned.

Architecture at a glance

• Drupal (Apache and PHP) serves plain HTTP on port 80. TLS is terminated upstream by a reverse proxy (Traefik on the RemarkableCloud App Platform). Set DRUPAL_TRUSTED_HOST to the public hostname so Drupal accepts requests for it.
• MariaDB is a separate database container and holds all content and configuration.
• A data volume at /opt/drupal/web/sites/default holds settings.php and uploaded files. Core and modules stay in the image.

Docker Compose walkthrough

The standalone stack (Drupal and MariaDB) is defined in the image’s docker-compose.yml:

name: drupal
services:
  db:
    image: mariadb:11
    restart: unless-stopped
    environment:
      MARIADB_DATABASE: drupal
      MARIADB_USER: drupal
      MARIADB_PASSWORD: ${DB_PASSWORD:-change-me-db}
      MARIADB_ROOT_PASSWORD: ${DB_ROOT_PASSWORD:-change-me-root}
    volumes: [db-data:/var/lib/mysql]
    healthcheck:
      test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
      interval: 10s
      timeout: 5s
      retries: 12
  drupal:
    image: ${DRUPAL_IMAGE:-ghcr.io/remarkablecloud/drupal:11.4.6-r1}
    restart: unless-stopped
    depends_on:
      db:
        condition: service_healthy
    ports: ["${HTTP_PORT:-8097}:80"]
    environment:
      DRUPAL_DB_HOST: db
      DRUPAL_DB_PORT: "3306"
      DRUPAL_DB_NAME: drupal
      DRUPAL_DB_USER: drupal
      DRUPAL_DB_PASSWORD: ${DB_PASSWORD:-change-me-db}
      DRUPAL_ADMIN_USER: ${DRUPAL_ADMIN_USER:-admin}
      DRUPAL_ADMIN_PASSWORD: ${DRUPAL_ADMIN_PASSWORD:-}
      DRUPAL_ADMIN_EMAIL: ${DRUPAL_ADMIN_EMAIL:-admin@example.com}
      DRUPAL_SITE_NAME: ${DRUPAL_SITE_NAME:-Drupal}
      DRUPAL_TRUSTED_HOST: ${DRUPAL_TRUSTED_HOST:-}
    volumes:
      - drupal-default:/opt/drupal/web/sites/default
volumes:
  db-data:
  drupal-default:

Step by step:

1. The app waits for the database. depends_on with condition: service_healthy avoids a first-boot race against MariaDB.
2. Install is headless. The DRUPAL_DB_* variables drive drush site:install; no web wizard.
3. The admin password is generated if blank. Leave DRUPAL_ADMIN_PASSWORD empty and the image creates a strong one on first install and logs it once.
4. Only the web port is exposed. ${HTTP_PORT:-8097}:80 is for local use; in production the proxy connects to port 80 on the internal network.
5. State lives in volumes. drupal-default (sites/default) and db-data persist across restarts and upgrades.

To start it locally:

DB_PASSWORD=$(openssl rand -hex 16) docker compose up -d

Then browse to http://localhost:8097 and read the admin login from docker compose logs drupal. For production, set DRUPAL_TRUSTED_HOST to your public hostname and put the container behind a TLS-terminating reverse proxy.

Environment variable reference

These are wired automatically by the App Platform backend from the managed MariaDB; they are listed here for standalone and self-hosted runs.

Variable	Required	Value / default	Purpose
DRUPAL_DB_HOST	yes	<db_host>	MariaDB host.
DRUPAL_DB_PORT	no	3306	MariaDB port.
DRUPAL_DB_NAME	yes	<db_name>	Database name.
DRUPAL_DB_USER	yes	<db_user>	Database user.
DRUPAL_DB_PASSWORD	yes	<db_password>	Database password.
DRUPAL_TRUSTED_HOST	no	<hostname>	Public hostname; written to trusted_host_patterns.
DRUPAL_ADMIN_USER	no	admin	Admin login created at install.
DRUPAL_ADMIN_PASSWORD	no	(generated)	Admin password. Leave empty to auto-generate on first install (printed once); set it to pin your own.
DRUPAL_ADMIN_EMAIL	no	admin@example.com	Admin email.
DRUPAL_SITE_NAME	no	Drupal	Site name.

Only the first install reads these; afterwards changes happen inside Drupal.

Hardening notes

• No baked credentials. The admin password is generated at first install or supplied by you, never stored in an image layer.
• Digest-pinned base. Each build is auditable and reproducible.
• Healthcheck gates traffic. /rc-health.txt must return success before the platform routes requests.
• Trusted host patterns. Set DRUPAL_TRUSTED_HOST so Drupal only answers for your hostname.
• Keep MariaDB private. Do not publish its port to the host or the internet.
• After install, review roles and permissions, keep Drupal and modules updated, and consider making settings.php read-only.

Backups

Capture the database and the data volume together:

1. The MariaDB database:

   docker compose exec db mariadb-dump -u root -p"$DB_ROOT_PASSWORD" drupal > drupal-db.sql

2. The data volume at sites/default (settings.php and uploaded files):

   docker run --rm -v drupal_drupal-default:/data -v "$PWD":/backup alpine \
     tar czf /backup/drupal-default.tgz -C /data .

On the RemarkableCloud App Platform, database and volume backups follow the platform’s backup schedule.

Upgrades

• New builds ship as new -r tags. Because core and modules live in the image and only sites/default is persisted, pulling a new tag updates Drupal core and modules; Drupal runs any database updates it needs:

  docker compose pull drupal && docker compose up -d drupal
  # then run database updates:
  docker compose exec drupal drush --root=/opt/drupal/web updatedb -y

• Manage modules with composer (an image rebuild), rather than the UI, so retag upgrades stay clean.
• Back up first, and keep the database dump and the sites/default archive from just before the upgrade.
• Read the changelog. Every build is listed in CHANGELOG.md with the base image digest and any behavior changes.