Drupal Staging Deployment v1.0

This solution provides automated staging deployment for Drupal applications using GitLab CI/CD and Docker Swarm with Traefik.

🚀 Quick Install

Online Install (Recommended):

curl -sSL https://stage-tools.tyche.q2.cz/drupal/v1.0/install.sh | bash

Download & Run:

curl -O https://stage-tools.tyche.q2.cz/drupal/v1.0/install.sh

chmod +x install.sh

./install.sh

Web Interface:
Visit https://stage-tools.tyche.q2.cz for a full solution browser.

Features

• 🚀 Optimized Docker builds with multi-stage building and composer caching


• 🔄 Automated CI/CD with GitLab pipelines including database setup


• 🌐 Traefik integration for automatic SSL and routing


• 🗄️ Automatic database management with MariaDB


• 📦 Frontend build support with Node.js (optional)


• 🛡️ Production-ready with security best practices


• 🔧 Flexible PHP extensions (SQL Server, ImageMagick, etc.)




Prerequisites




• Drupal project with composer.json


• GitLab repository with CI/CD enabled


• Docker Swarm cluster with Traefik


• GitLab runners with Docker support


• MariaDB/MySQL database server




Installation





🌐 Web Interface (Recommended)



Visit the Stage Tools Web Interface to browse solutions and get installation commands:

https://stage-tools.tyche.q2.cz

The web interface provides:

• 📖 Interactive documentation with syntax highlighting


• 💾 Copy-paste installation commands for multiple methods


• 🔍 Solution browser with status and features


• 📋 Template previews and configuration examples




Manual Installation



If you prefer command-line installation:



Manual Installation



If you prefer command-line installation:



Clone stage-tools repository


git clone git@gitlab.com:your-org/stage-tools.git /tmp/stage-tools



Run installer from your Drupal project root


cd /path/to/your/drupal/project

/tmp/stage-tools/drupal/default/v1.0/install.sh



Clean up


rm -rf /tmp/stage-tools





Manual Installation



1. Download the install script:


wget https://gitlab.com/your-org/stage-tools/-/raw/main/drupal/default/v1.0/install.sh

chmod +x install.sh



2. Run the interactive setup:


./install.sh





Configuration



The script will ask for:


• Project details - Name, Drupal version, PHP version


• Document root - Usually web, docroot, or public


• Frontend build - Node.js version if you have theme/module builds


• PHP extensions - Standard Drupal extensions plus optional ones


• Database settings - Host, port for your MariaDB server


• Domain configuration - Your deployment domain


• GitLab runners - Tags for your build and deploy runners


• Traefik settings - Network and certificate resolver




Generated Files



After installation, you'll have:



your-drupal-project/

├── .gitlab-ci.yml                           # GitLab CI/CD pipeline

├── .dockerignore                            # Docker build optimization

└── .q2/

    └── staging/

        ├── Dockerfile.stage                 # Optimized Drupal Dockerfile

        ├── docker-entrypoint.sh             # Container startup script

        ├── generate-drupal-compose.sh       # Dynamic compose generator

        └── deploy/

            └── ci/

                └── docker-compose.stage.yml # Docker Swarm configuration





Usage



1. Create cron schedule file for your environment:


Create crontab-stage.txt


echo "0 /6    /usr/local/bin/drush cron" > crontab-stage.txt



2. Configure GitLab CI/CD variables:
- MYSQL_ROOT_PASSWORD - Database root password
- MYSQL_HOST - Database server address
- MYSQL_PORT - Database server port

3. Set up .env file with basic configuration:


APP_ENV=local

DATABASE_URL=mysql://user:pass@localhost:3306/dbname



4. Push to staging branch:


git push origin stage



5. Monitor deployment in GitLab CI/CD pipelines

6. Access your application at:


https://[project-name].[domain-suffix]





Pipeline Stages



The GitLab CI pipeline includes:

1. Prepare - Generate Docker configurations from DDEV setup
2. Build - Create optimized Docker image with caching
3. DB Setup - Create database and user automatically
4. Deploy - Deploy to Docker Swarm with health checks



Customization





PHP Extensions



The installer supports various PHP extensions:

Standard Drupal extensions:

• mysqli, pdo_mysql - Database connectivity


• gd, intl, zip, xml - Core Drupal requirements


• opcache, bcmath, ftp - Performance and functionality


Optional extensions:

• SQL Server support (sqlsrv, pdo_sqlsrv)


• ImageMagick support (imagick)




Frontend Build



If you have Node.js assets (themes, modules):

• The installer detects package.json and .ddev/config.yaml


• Installs Node.js in the container


• Runs npm run build or yarn build during image creation




Environment Settings



The deployment creates:

• settings.stage.php - Database and Drupal configuration


• services.stage.yml - Caching and performance settings


• Environment-specific cron scheduling




Database Management



The pipeline automatically:

• Creates database with UTF8MB4 collation


• Creates user with generated secure password


• Generates Drupal hash salt


• Passes credentials to deployment




Advanced Configuration





Custom Dockerfile



To modify the Dockerfile generation, edit:


.q2/staging/generate-drupal-compose.sh





Multiple Environments



Create variants for different environments:


Copy and customize for production


cp crontab-stage.txt crontab-prod.txt

Modify schedule as needed





Database Import



To import existing database during deployment, place:

• sql/stage.sql or sql/stage.sql.gz in your project


• Or set SQL_DUMP_URL GitLab variable




Troubleshooting





Common Issues



1. "No composer.json found"
- Run the script from your Drupal project root

2. Database connection fails
- Check MYSQL_HOST and MYSQL_PORT variables
- Verify database server is accessible from GitLab runners
- Check MYSQL_ROOT_PASSWORD is correct

3. Build fails with PHP extensions
- Review the generated Dockerfile.stage
- Some extensions may need additional system packages

4. Deployment fails
- Check GitLab runner has Docker Swarm access
- Verify Traefik network exists and is accessible
- Check container logs: docker service logs [service-name]



Logs and Debugging




• GitLab CI logs: Check pipeline output in GitLab


• Container logs: Use docker service logs [project-name]_app


• Database setup: Check db_setup stage output


• Health checks: Visit https://yourdomain.com/health.php




Security Considerations




• Database passwords are automatically generated


• Never commit .env files with real credentials


• Use GitLab CI/CD variables for sensitive data


• SSL is enforced through Traefik


• Container runs as non-root user


• Regular security updates through base image updates




Performance Features




• Multi-stage Docker builds for smaller images


• Composer caching to speed up builds


• Registry caching to reuse layers


• OPcache enabled for PHP performance


• Database connection pooling ready


• Asset optimization with frontend builds




Migration from Existing Setup



If migrating from manual Docker/server setup:

1. Backup existing configuration
2. Run the installer in a test environment first
3. Compare generated files with your custom ones
4. Migrate custom settings to generated templates
5. Test thoroughly before production migration



Drupal-Specific Features




• Settings management with environment-specific files


• Cron scheduling with container-native approach


• File management with persistent volumes


• Private files support with separate volume


• Trusted host patterns automatically configured


• Reverse proxy configuration for Traefik




Support




• Check generated files and their inline documentation


• Review GitLab CI/CD pipeline logs for specific errors


• Test Docker builds locally: docker build -f .q2/staging/Dockerfile.stage .


• Verify database connectivity before deployment