Drupal: Difference between revisions
Added the PHP category |
|||
| (4 intermediate revisions by 2 users not shown) | |||
| Line 45: | Line 45: | ||
==== Capturing Server Resources Before Your Next Rebuild ==== | ==== Capturing Server Resources Before Your Next Rebuild ==== | ||
After installing Drupal on NixOS using the admin UI, you will want to export the MYSQL database of your website and export the Drupal site configuration. Doing both steps makes it possible to implement continuous integration and continuous delivery on the environment you just created. | After installing Drupal on NixOS using the admin UI, you will want to export the MYSQL database of your website and export the Drupal site configuration. Doing both steps makes it possible to implement continuous integration and continuous delivery on the environment you just created. | ||
Backing up your Drupal configuration (with git or similar) and database is recommended, especially after a successful install of a new Drupal instance.<blockquote>'''Warning:''' When using a Drupal package that has an existing set of configuration in the config sync directory (or using the configRoot option in nix), it is '''mandatory''' to import a working SQL database from another working installation. Failing to do so will cause your website to not function correctly. | |||
The advised development workflow for starting a Drupal website (or websites) on NixOS is to do the following | |||
# Install a new instance of Drupal on NixOS. The configRoot option should be disabled. | |||
# Once the installation is complete, export the database, and export the configuration. See the sections below on the recommended way to do both of these tasks. | |||
# Integrate the contents of the config sync directory (located, by default, at /var/lib/drupal/<hostname>/config) back into your upstream Drupal package. | |||
# During your next rebuild, make sure to import any configuration changes by visiting '''Manage > Configuration > Development > Configuration synchronization''' in the Drupal admin. | |||
# If you intend on deploying this exact same site elsewhere, take regular backups of your database. | |||
# Deploy your saved database and the source code into a new instance of Drupal on NixOS at the same time to avoid a chicken-and-egg scenario. | |||
</blockquote> | |||
===== Exporting The Database ===== | ===== Exporting The Database ===== | ||
| Line 75: | Line 87: | ||
Generally, you should integrate the config you export from the NixOS environment back into a git repo that also contains your Drupal source code. This will ensure that the Drupal instance you deploy into NixOS can import any config changes from git. | Generally, you should integrate the config you export from the NixOS environment back into a git repo that also contains your Drupal source code. This will ensure that the Drupal instance you deploy into NixOS can import any config changes from git. | ||
If | If your Drupal package comes with configuration in a config sync directory (or similar), make sure to tell NixOS where to find it with this expression.<syntaxhighlight lang="nix"> | ||
# Tell NixOS where to look for the config sync directory in the Drupal package. | # Tell NixOS where to look for the config sync directory in the Drupal package. | ||
services.drupal.sites."my-host-name.local".configRoot = "/config"; | services.drupal.sites."my-host-name.local".configRoot = "/config"; | ||
| Line 81: | Line 93: | ||
# The contents of the /config directory (defined above) will be copied into the path defined by the configSyncDir setting MINUS the trailing "/sync" path, if it exists. | # The contents of the /config directory (defined above) will be copied into the path defined by the configSyncDir setting MINUS the trailing "/sync" path, if it exists. | ||
services.drupal.sites."my-host-name.local".configSyncDir = "/var/lib/drupal/my-host-name.local/config/sync"; | services.drupal.sites."my-host-name.local".configSyncDir = "/var/lib/drupal/my-host-name.local/config/sync"; | ||
</syntaxhighlight>If you use the default setting for <code>configSyncDir</code>, you can simply add the first line of code and | </syntaxhighlight>If you use the default setting for <code>configSyncDir</code>, you can simply add the first line of code and substitute your hostname. | ||
== Configuration == | == Configuration == | ||
=== Configuration Using settings.php === | === Configuration Using settings.php === | ||
Drupal uses a file called <code>settings.php</code> to configure the application at a | Drupal uses a file called <code>settings.php</code> to configure the application at a low level. If you use the NixOS-provided Drupal package instead of a custom package, you may want to change some of these settings. | ||
You can do this by writing pure PHP into the <code>services.drupal.sites.<name>.extraSettings</code> key<syntaxhighlight lang="nix"> | You can do this by writing pure PHP into the <code>services.drupal.sites.<name>.extraSettings</code> key<syntaxhighlight lang="nix"> | ||
| Line 107: | Line 118: | ||
=== Webserver Configuration === | === Webserver Configuration === | ||
You can use either [[nginx]] or [[caddy]] as the webserver, but only one may be used at a time. All Drupal installations on NixOS will use the same configured webserver, though configuration may be customized for each installation. | You can use either [[nginx]] or [[caddy]] as the webserver, but only one may be used at a time. All Drupal installations on NixOS will use the same configured webserver, though webserver configuration may be customized for each installation. | ||
Nginx is the default webserver, though you can use caddy by writing this configuration<syntaxhighlight lang="nix"> | Nginx is the default webserver, though you can use caddy by writing this configuration<syntaxhighlight lang="nix"> | ||
| Line 151: | Line 162: | ||
}; | }; | ||
</syntaxhighlight><blockquote>'''Note:''' The database settings configured in NixOS will merely create the database, they will not instruct a new Drupal installation where to find the database. Either define your database settings in <code>settings.php</code>, or see [[Drupal#After_Installation| After Installation]] for an example of how to do this with nix.</blockquote> | </syntaxhighlight><blockquote>'''Note:''' The database settings configured in NixOS will merely create the database, they will not instruct a new Drupal installation where to find the database. Either define your database settings in <code>settings.php</code>, or see [[Drupal#After_Installation| After Installation]] for an example of how to do this with nix.</blockquote> | ||
=== Hostname Configuration === | |||
The hostname string configured under <code>services.drupal.sites.<sitename></code> can be used to create a publicly accessible hostname for your website. However, the Drupal service does not do this by default. | |||
In order to modify your <code>/etc/hosts</code> file, use this configuration in conjunction with your site config. | |||
<syntaxhighlight lang="nix"> | |||
services.drupal = { | |||
enable = true; | |||
sites = { | |||
"mysite.com" = { | |||
enable = true; | |||
}; | |||
}; | |||
}; | |||
# Enumerate our custom host into /etc/hosts | |||
networking.hosts = { | |||
"127.0.0.1" = ["localhost" "mysite.com"]; | |||
}; | |||
</syntaxhighlight> | |||
== State Directory == | == State Directory == | ||
| Line 156: | Line 188: | ||
This is the file structure you can find at a typical installation<syntaxhighlight lang="bash"> | This is the file structure you can find at a typical installation<syntaxhighlight lang="bash"> | ||
$ pwd | |||
/var/lib/drupal/localhost | |||
$ ls | $ ls | ||
config modules private sites themes | config modules private sites themes | ||
| Line 161: | Line 195: | ||
</syntaxhighlight>Files in this directory, because of their tendency to change during run time, cannot live inside of <code>/nix/store</code>, so they are placed here instead. | </syntaxhighlight>Files in this directory, because of their tendency to change during run time, cannot live inside of <code>/nix/store</code>, so they are placed here instead. | ||
The webserver is the default owner of all files in the state directory and regular users are not permitted to access this directory by default. However, users who belong to the webserver group may edit or upload files | The webserver is the default owner of all files in the state directory and regular users are not permitted to access this directory by default. However, users who belong to the webserver group may edit or upload files. | ||
Refer to [[Drupal#How To Access Files In The State Directory As A Regular User|How To Access Files In The State Directory As A Regular User]] for more information on how to add users to the webserver group. | |||
=== Uploading Modules and Themes === | === Uploading Modules and Themes === | ||
The <code>modules</code> and <code>themes</code> directories of the state directory are symlinked directly to the Drupal installation in the nix store. Users can upload both [https://www.drupal.org/docs/user_guide/en/extend-manual-install.html modules and themes] to these directories and Drupal will detect them. | The <code>modules</code> and <code>themes</code> directories of the state directory are symlinked directly to the Drupal installation in the nix store. Users can upload both [https://www.drupal.org/docs/user_guide/en/extend-manual-install.html modules and themes] to these directories and Drupal will detect them. | ||
This is not the officially [https://www.drupal.org/docs/extending-drupal/installing-modules recommended method] for installing contributed modules and themes, or modules and themes that have third-party dependencies. However, this functionality has been preserved both as an escape hatch, and to provide an easy way to manage a simple Drupal install that doesn't rely on [https://getcomposer.org/ composer]. | This is not the officially [https://www.drupal.org/docs/extending-drupal/installing-modules recommended method] for installing contributed modules and themes, or modules and themes that have third-party dependencies. However, this functionality has been preserved both as an escape hatch, and to provide an easy way to manage a simple Drupal install that doesn't rely exclusively on [https://getcomposer.org/ composer]. | ||
=== Changing The Location Of The State Directory === | === Changing The Location Of The State Directory === | ||
| Line 172: | Line 208: | ||
services.drupal.sites."localhost".stateDir = /path/to/custom/state/dir; | services.drupal.sites."localhost".stateDir = /path/to/custom/state/dir; | ||
</syntaxhighlight><blockquote>'''Note''': Changing the state directory does not automatically change the location of the <code>modules</code>, <code>themes</code>, <code>config</code>, or <code>files</code> directories. You can override those locations by using the <code>modulesDir</code> and <code>themesDir</code>, <code>configDir</code>, <code>filesDir</code> keys, accordingly.</blockquote> | </syntaxhighlight><blockquote>'''Note''': Changing the state directory does not automatically change the location of the <code>modules</code>, <code>themes</code>, <code>config</code>, or <code>files</code> directories. You can override those locations by using the <code>modulesDir</code> and <code>themesDir</code>, <code>configDir</code>, <code>filesDir</code> keys, accordingly.</blockquote> | ||
[[Category:Server]] | |||
[[Category:Web Applications]] | |||
[[Category:PHP]] | |||