drin.rst: add some notes about administrative database access
[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
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 excute `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 SEE ALSO
126 ========
127
128 * drupal-composer/drupal-project: https://github.com/drupal-composer/drupal-project
129 * drush: https://github.com/drush-ops/drush
130 * drupal-console: https://github.com/hechoendrupal/drupal-console
131
132 .. _drupal-composer/drupal-project: https://github.com/drupal-composer/drupal-project
133 .. _drush: https://github.com/drush-ops/drush
134 .. _drupal-console: https://github.com/hechoendrupal/drupal-console
135
136 BUGS
137 ====
138
139 None known.