bootstrap.sh: don't force RewriteBase, it's not generally needed
[drupal-init-tools.git] / 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.