drin.rst

   1 ======
   2  drin
   3 ======
   4
   5 -----------------
   6 Drupal init tools
   7 -----------------
   8
   9 :Author: Antonio Ospite <ao2@ao2.it>
  10 :Date:   2017-06-20
  11 :Copyright: GPLv2+
  12 :Manual section: 1
  13 :Manual group: General Commands Manual
  14
  15 SYNOPSIS
  16 ========
  17
  18 *drin* <options> [sub-command]
  19
  20 DESCRIPTION
  21 ===========
  22
  23 Helper commands to create and install new Drupal projects.
  24
  25 One problem with setting up a new Drupal project with
  26 drupal-composer/drupal-project is that drush and drupal-console are not
  27 available until the site dependencies have been downloaded, drupal-init-tools
  28 helps to solve this and also adds a nicer command line interface to some
  29 repetitive tasks.
  30
  31 drupal-init-tools commands are especially useful when setting up projects in
  32 user web directories[1].
  33
  34 [1] http://httpd.apache.org/docs/current/howto/public_html.html
  35
  36
  37 OPTIONS
  38 =======
  39
  40 Available options:
  41
  42   **-h**, **--help**
  43     this help
  44
  45
  46 Available sub-commands:
  47
  48   ``new`` `[-h|--help]` `<destdir>` `[composer options (e.g. --devel)]`
  49     Create a new Drupal project in the `destdir` directory.
  50
  51   ``bootstrap`` `[--devel|--overwrite-profile|-h|--help]`
  52     Bootstrap a Drupal project, using settings from a `bootstrap.conf` file.
  53
  54   ``clean`` `[-h|--help]`
  55     Cleanup the project, removing all the installed files.
  56
  57   ``create-profile`` `[-h|--help]` `<title>` `<machine_name>`
  58     Create an installation profile from the installed project.
  59
  60
  61 EXAMPLES OF USE
  62 ===============
  63
  64 Create and install a new Drupal project:
  65
  66 ::
  67
  68   cd ~/public_html
  69   drin new drupal_test_site
  70   cd drupal_test_site
  71   $EDITOR bootstrap.conf
  72   drin bootstrap --devel
  73
  74
  75 Create an installation profile from the currently installed project:
  76
  77 ::
  78
  79   drin create-profile "Test Profile" test_profile
  80
  81
  82 Clean and rebuild the whole project to verify that installing from scratch works:
  83
  84 ::
  85
  86   drin clean
  87   drin bootstrap
  88
  89 NOTES ON DATABASE SETUP
  90 =======================
  91
  92 The `bootstrap` command in `drupal-init-tools` uses `drush` for the site
  93 installation, and `drush` requires MySQL super-user access to create new MySQL
  94 users and databases.
  95
  96 On some Linux distributions, like Debian, the MariaDB server is configured by
  97 default to only allow access to the `root` user via the `unix_socket` plugin,
  98 making it unusable by `drush`. In these cases it's recommended to create e new
  99 MySQL super-user.
 100
 101 For password-less access create a MySQL admin user correspondent to the system
 102 user which will execute `drush` (e.g. the current user):
 103
 104 ::
 105
 106   sudo /usr/bin/mysql -e "GRANT ALL ON *.* TO '$USER'@'localhost' IDENTIFIED VIA unix_socket WITH GRANT OPTION"
 107
 108
 109 For password regulated access create a user with a password:
 110
 111 ::
 112
 113   sudo /usr/bin/mysql -e "GRANT ALL ON *.* TO 'USERNAME'@'localhost' IDENTIFIED BY 'password' WITH GRANT OPTION"
 114
 115
 116 For details see also the **PASSWORDS** section in the README.Debian file
 117 provided by the mariadb-server Debian package, either in
 118 `/usr/share/doc/mariadb-server-10.1/README.Debian.gz` or at
 119 https://salsa.debian.org/mariadb-team/mariadb-10.1/blob/stretch/debian/mariadb-server-10.1.README.Debian#L73
 120
 121 The settings in the `bootstrap.conf` file have to be adjusted according to how
 122 super-user access has been configured.
 123
 124
 125 NOTES ON WEB SERVER SETUP
 126 =========================
 127
 128 The `bootstrap` command in  `drupal-init-tools` supports installing new sites
 129 in *user dirs*; this means that users can have the Drupal sites in their home
 130 directories, usually under the `public_html/` sub-directory.
 131
 132 This may make development more comfortable, as new work can be done in the
 133 usual development environment (git and ssh configuration, editor settings,
 134 etc.).
 135
 136 To configure the Apache web server to enable *user dirs*, first enable the
 137 module:
 138
 139 ::
 140
 141   sudo a2enmod userdir
 142
 143 And then make sure that the configuration is compatible with Drupal, changes
 144 like the following may be necessary, depending on the distribution:
 145
 146 ::
 147
 148   diff --git a/apache2/mods-available/php7.2.conf b/apache2/mods-available/php7.2.conf
 149   index d4df3e5..0758ea6 100644
 150   --- a/apache2/mods-available/php7.2.conf
 151   +++ b/apache2/mods-available/php7.2.conf
 152   @@ -18,8 +18,8 @@
 153    # To re-enable PHP in user directories comment the following lines
 154    # (from <IfModule ...> to </IfModule>.) Do NOT set it to On as it
 155    # prevents .htaccess files from disabling it.
 156   -<IfModule mod_userdir.c>
 157   -    <Directory /home/*/public_html>
 158   -        php_admin_flag engine Off
 159   -    </Directory>
 160   -</IfModule>
 161   +#<IfModule mod_userdir.c>
 162   +#    <Directory /home/*/public_html>
 163   +#        php_admin_flag engine Off
 164   +#    </Directory>
 165   +#</IfModule>
 166   diff --git a/apache2/mods-available/userdir.conf b/apache2/mods-available/userdir.conf
 167   index 2c334ec..737abdf 100644
 168   --- a/apache2/mods-available/userdir.conf
 169   +++ b/apache2/mods-available/userdir.conf
 170   @@ -3,7 +3,7 @@
 171           UserDir disabled root
 172
 173           <Directory /home/*/public_html>
 174   -             AllowOverride FileInfo AuthConfig Limit Indexes
 175   +             AllowOverride FileInfo AuthConfig Limit Indexes Options
 176                   Options MultiViews Indexes SymLinksIfOwnerMatch IncludesNoExec
 177                   Require method GET POST OPTIONS
 178           </Directory>
 179
 180 These changes are typically only applied once, after the first installation of
 181 the web server.
 182
 183 SEE ALSO
 184 ========
 185
 186 * drupal-composer/drupal-project: https://github.com/drupal-composer/drupal-project
 187 * drush: https://github.com/drush-ops/drush
 188 * drupal-console: https://github.com/hechoendrupal/drupal-console
 189
 190 .. _drupal-composer/drupal-project: https://github.com/drupal-composer/drupal-project
 191 .. _drush: https://github.com/drush-ops/drush
 192 .. _drupal-console: https://github.com/hechoendrupal/drupal-console
 193
 194 BUGS
 195 ====
 196
 197 None known.