Replacing Legacy Drupal Setup Scripts with Configuration Management
How to decide what belongs in exported configuration, database content, update hooks, and editorial workflows.
Drupal projects often accumulate setup scripts that create fields, alter editor configuration, seed content, and repair environment differences. They can be useful during discovery, but leaving them in the permanent deployment path creates a second configuration system alongside Drupal’s own APIs.
Separate configuration from content
Configuration describes how the application behaves: content types, fields, view modes, text formats, Views, module settings, and theme settings. Those definitions belong in the configuration export and should move through version control.
Content is the material editors manage: portfolio sections, journal articles, taxonomy terms, and contact submissions. It belongs in the database and should be created or revised through Drupal’s entity forms, migrations, or carefully designed editorial workflows.
Why repeated setup scripts become risky
- They can overwrite editorial changes on every deployment.
- Their assumptions drift away from exported configuration.
- They may behave differently when an entity already exists.
- They hide schema changes from normal configuration review.
- They make production content depend on developer-only bootstrap logic.
In this project, early scripts configured CKEditor, created portfolio structures, seeded journal material, and submitted search-engine notifications. Once the site model stabilized, those responsibilities moved to configuration, normal Drupal content, and supported modules.
A cleaner deployment contract
The repository now owns active configuration in config/sync. Deployment checks for pending database updates, imports that configuration from an explicit source directory, rebuilds caches, and executes deploy hooks. It does not recreate content entities or modify field storage on every release.
Explicitly naming the configuration source is important when environments have different local settings. The same version-controlled configuration is imported even if a host previously used a machine-specific sync directory.
Use update and deploy hooks for code-driven transitions
Some changes cannot be expressed by configuration alone. Schema transitions belong in update hooks, while post-deployment actions that depend on updated code and configuration belong in deploy hooks. These hooks are versioned, run once, and participate in Drupal’s deployment model.
Keep environment differences narrow
Development-only modules such as Devel should be enabled through an environment-specific approach rather than exported into production configuration. Config Split can help when there is a real set of environment-owned differences. Config Ignore is better reserved for narrowly justified settings that genuinely must remain locally managed.
The resulting editorial model
The portfolio is a proper node composed of reusable Paragraph components. Journal entries are normal nodes with fields for excerpt, slug, difficulty, reading time, categories, tags, and body. Editors can work through Gin and CKEditor without touching PHP, while developers can review structural changes as configuration.