README.adoc 4.42 KB
Newer Older
Emmanuel Milou's avatar
Emmanuel Milou committed
1
// This document is included in every project that submodules it.
Emmanuel Milou's avatar
Emmanuel Milou committed
2
= README
Emmanuel Milou's avatar
Emmanuel Milou committed
3

Emmanuel Milou's avatar
Emmanuel Milou committed
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
= Configuration

The file `default_vars.py` contains the default configuration.

CAUTION: You should not edit this file directly.

Instead, copy the file in a file named `local_vars.py`.

  $ cp default_vars.py local_vars.py

The configuration specified in this new file will be loaded by Drupalizer and will override the default configuration.

== Section

The configuration parameters are grouped in section, to ease maintenance and readability.
All those variables are loaded as Fabric environment variables.

=== Project settings

Those are global project parameters mandatory to Drupalizer.

|===
|Parameters |Description

|_project_name_
|Machine-name of the project.

|_workspace_
|Project root directory.

|_interactive_mode_
35
|If False, no prompt. Useful for Jenkins.
Emmanuel Milou's avatar
Emmanuel Milou committed
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90

|_locale_
|If True, install the site in French.

|===

=== Site settings

|===
|Parameters |Description

|_site_root_
|Drupal root. Usually _src/drupal_.

|_site_name_
|Drupal site name. Set during installation.

|_site_environment_
|Default: _local_.

|_site_profile_
|The installation profile, if any.

|_site_profile_repo_
|The installation profile git repository, if applicable.

|_site_profile_makefile_
|The Drush Makefile to run to build the platform.

|_site_db_user_
|The database user name. Default: _dev_.

|_site_db_pass_
|The database password. Default: _dev_.

|_site_db_host_
|The database hostname. Default: _localhost_

|_site_db_name_
| The database name

|_site_hostname_
|The site hostname (Optional).

|_site_admin_user_
|The Drupal administrator user name. Default: _admin_.

|_site_admin_pass_
|The Drupal administrator password. Default: _admin_.

|_site_subdir_
|The Drupal site directory (only for multisite). Default: _default_.

|===

91
92
93
94
95
96
97
98
99
100
=== Patternlab settings

|===
|Parameters |Description

|_patternlab_dir_
|The Patternlab directory. Default: _empty_

|===

Emmanuel Milou's avatar
Emmanuel Milou committed
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
=== Docker-related settings

|===
|Parameters |Description

|_docker_workspace_
|The Docker workspace. Default: _/opt/sfl_

|_docker_site_root_
|Drupal root in the Docker container. Default: _/opt/sfl/src/drupal_.

|bind_port
|The Docker port. Default: _8001_.

|_apache_user_
|The user running Apache in the Docker container. Default: _www-data_.

|_container_ip_
|Docker auto-added container IP. **Do not edit**.

|===

=== Target environments settings

TODO


= Fabric tasks
Emmanuel Milou's avatar
Emmanuel Milou committed
129
130
131

*Drupalizer* is a Fabric script on top of Docker and tightly integrated with Drush and Drupal that provides the developer high-level tasks to manage the local development environment.

Emmanuel Milou's avatar
Emmanuel Milou committed
132
TIP: Drupalizer should be configured as a git submodule for every project that needs to use it.
Emmanuel Milou's avatar
Emmanuel Milou committed
133
134
135
136
137

For a complete overview of all available commands, run:

 $ fab --list

Emmanuel Milou's avatar
Emmanuel Milou committed
138
139
140
141
To get a more nested or tree-like view, pass the following option:

 $ fab --list-format=nested --list

Emmanuel Milou's avatar
Emmanuel Milou committed
142
== Top-level tasks
Emmanuel Milou's avatar
Emmanuel Milou committed
143

Emmanuel Milou's avatar
Emmanuel Milou committed
144
The top-levels tasks are larger tasks that include others. They are the most commonly called tasks.
Emmanuel Milou's avatar
Emmanuel Milou committed
145
146
147

* _Setup_ the Docker container, and _run_ a full Drupal installation:

Emmanuel Milou's avatar
Emmanuel Milou committed
148
 $ fab init
Emmanuel Milou's avatar
Emmanuel Milou committed
149

Emmanuel Milou's avatar
Emmanuel Milou committed
150
* _Run_ the Drupal installation
Emmanuel Milou's avatar
Emmanuel Milou committed
151

Emmanuel Milou's avatar
Emmanuel Milou committed
152
 $ fab install
Emmanuel Milou's avatar
Emmanuel Milou committed
153

Emmanuel Milou's avatar
Emmanuel Milou committed
154
155
156
CAUTION: This command will wipe all the modifications made in the working directories.

* _Update_ the Drupal installation
Emmanuel Milou's avatar
Emmanuel Milou committed
157

Emmanuel Milou's avatar
Emmanuel Milou committed
158
  $ fab update
Emmanuel Milou's avatar
Emmanuel Milou committed
159

Emmanuel Milou's avatar
Emmanuel Milou committed
160
161
162
CAUTION: This command may wipe the modifications made in the working directories.


Emmanuel Milou's avatar
Emmanuel Milou committed
163
 * _Configure_ and _run_ the Behat tests:
Emmanuel Milou's avatar
Emmanuel Milou committed
164

Emmanuel Milou's avatar
Emmanuel Milou committed
165
 $ fab test
Emmanuel Milou's avatar
Emmanuel Milou committed
166

Emmanuel Milou's avatar
Emmanuel Milou committed
167
TIP: The formatters used are _pretty_ and _junit_.
Emmanuel Milou's avatar
Emmanuel Milou committed
168

169
170
171
172
173
174
175
176
* _Deploy_ the Drupal installation to a Web Server

 $ fab deploy:dev

TIP: 'dev' is the environment to deploy the Drupal installation, see the default_vars.py file.

* _Deploy_ the Drupal installation to Aegir

177
 $ fab --set=build_number=1,migrate=true,remove_platform=true deploy:dev
178

179
TIP: 'migrate' and 'remove_platform' are optionals parameters but 'build_number' is not, you should pass it always with a different value.
Emmanuel Milou's avatar
Emmanuel Milou committed
180

Emmanuel Milou's avatar
Emmanuel Milou committed
181
== Other common tasks
Emmanuel Milou's avatar
Emmanuel Milou committed
182
183

Some more atomic tasks supported by *Drupalizer* would be:
Emmanuel Milou's avatar
Emmanuel Milou committed
184
185
186

* _Start/stop_ the Docker container:

Emmanuel Milou's avatar
Emmanuel Milou committed
187
188
 $ fab docker.container_start
 $ fab docker.container_stop
Emmanuel Milou's avatar
Emmanuel Milou committed
189

Emmanuel Milou's avatar
Emmanuel Milou committed
190
 * _Bash_ into the Docker container:
Emmanuel Milou's avatar
Emmanuel Milou committed
191

Emmanuel Milou's avatar
Emmanuel Milou committed
192
  $ fab docker.connect
Emmanuel Milou's avatar
Emmanuel Milou committed
193

Emmanuel Milou's avatar
Emmanuel Milou committed
194
* _Run_ the Behat tests (without configure):
Emmanuel Milou's avatar
Emmanuel Milou committed
195

Emmanuel Milou's avatar
Emmanuel Milou committed
196
 $ fab behat.run
Emmanuel Milou's avatar
Emmanuel Milou committed
197

Emmanuel Milou's avatar
Emmanuel Milou committed
198
* _Update_ the full codebase by running the top-level Makefile:
Emmanuel Milou's avatar
Emmanuel Milou committed
199

Emmanuel Milou's avatar
Emmanuel Milou committed
200
 $ fab drush.make
Emmanuel Milou's avatar
Emmanuel Milou committed
201

Emmanuel Milou's avatar
Emmanuel Milou committed
202
203
CAUTION: This command will wipe all the modifications made in the working directories.

Emmanuel Milou's avatar
Emmanuel Milou committed
204
* _Archive_ the full codebase and the database using drush archive_dump:
Emmanuel Milou's avatar
Emmanuel Milou committed
205

Emmanuel Milou's avatar
Emmanuel Milou committed
206
 $ fab drush.archive_dump
207
208
209
210

* _Generate_ the guide style:

 $ fab patternlab.build