README.adoc 4.78 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
= 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

23
Those are global project parameters mandatory to Drupalizer.
Emmanuel Milou's avatar
Emmanuel Milou committed
24
25
26
27
28
29
30
31
32
33

|===
|Parameters |Description

|_project_name_
|Machine-name of the project.

|_workspace_
|Project root directory.

34
35
36
|_always_use_pty_
|This env var is defined by Fabric itself, and it's defaut value is True.
|You can easily pass it to False, addinf --no-pty to your fab command line. Useful in Jenkins jobs.
Emmanuel Milou's avatar
Emmanuel Milou committed
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59

|===

=== 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.

60
61
62
|_site_profile_branch_
|Branch you want to use to access to site makefile.

Emmanuel Milou's avatar
Emmanuel Milou committed
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
|_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_.

Philippe Mouchel's avatar
Philippe Mouchel committed
90
|_site_languages_
Philippe Mouchel's avatar
Philippe Mouchel committed
91
92
93
94
|The languages for which the translation files will be downloaded (separate with comma). Default: _''_.

|_site_default_language_
|The default language for site installation. Default: _''_.
Philippe Mouchel's avatar
Philippe Mouchel committed
95

Emmanuel Milou's avatar
Emmanuel Milou committed
96
97
|===

98
99
100
101
102
103
104
105
106
107
=== Patternlab settings

|===
|Parameters |Description

|_patternlab_dir_
|The Patternlab directory. Default: _empty_

|===

Emmanuel Milou's avatar
Emmanuel Milou committed
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
=== 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
136
137
138

*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
139
TIP: Drupalizer should be configured as a git submodule for every project that needs to use it.
Emmanuel Milou's avatar
Emmanuel Milou committed
140
141
142
143
144

For a complete overview of all available commands, run:

 $ fab --list

Emmanuel Milou's avatar
Emmanuel Milou committed
145
146
147
148
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
149
== Top-level tasks
Emmanuel Milou's avatar
Emmanuel Milou committed
150

Emmanuel Milou's avatar
Emmanuel Milou committed
151
The top-levels tasks are larger tasks that include others. They are the most commonly called tasks.
Emmanuel Milou's avatar
Emmanuel Milou committed
152
153
154

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

Emmanuel Milou's avatar
Emmanuel Milou committed
155
 $ fab init
Emmanuel Milou's avatar
Emmanuel Milou committed
156

Emmanuel Milou's avatar
Emmanuel Milou committed
157
* _Run_ the Drupal installation
Emmanuel Milou's avatar
Emmanuel Milou committed
158

Emmanuel Milou's avatar
Emmanuel Milou committed
159
 $ fab install
Emmanuel Milou's avatar
Emmanuel Milou committed
160

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

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

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

Emmanuel Milou's avatar
Emmanuel Milou committed
167
168
169
CAUTION: This command may wipe the modifications made in the working directories.


Emmanuel Milou's avatar
Emmanuel Milou committed
170
 * _Configure_ and _run_ the Behat tests:
Emmanuel Milou's avatar
Emmanuel Milou committed
171

Emmanuel Milou's avatar
Emmanuel Milou committed
172
 $ fab test
Emmanuel Milou's avatar
Emmanuel Milou committed
173

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

176
177
178
179
180
181
182
183
* _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

184
 $ fab --set=build_number=1,migrate=true,remove_platform=true deploy:dev
185

186
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
187

Emmanuel Milou's avatar
Emmanuel Milou committed
188
== Other common tasks
Emmanuel Milou's avatar
Emmanuel Milou committed
189
190

Some more atomic tasks supported by *Drupalizer* would be:
Emmanuel Milou's avatar
Emmanuel Milou committed
191
192
193

* _Start/stop_ the Docker container:

Emmanuel Milou's avatar
Emmanuel Milou committed
194
195
 $ fab docker.container_start
 $ fab docker.container_stop
Emmanuel Milou's avatar
Emmanuel Milou committed
196

Emmanuel Milou's avatar
Emmanuel Milou committed
197
 * _Bash_ into the Docker container:
Emmanuel Milou's avatar
Emmanuel Milou committed
198

Emmanuel Milou's avatar
Emmanuel Milou committed
199
  $ fab docker.connect
Emmanuel Milou's avatar
Emmanuel Milou committed
200

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

Emmanuel Milou's avatar
Emmanuel Milou committed
203
 $ fab behat.run
Emmanuel Milou's avatar
Emmanuel Milou committed
204

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

Emmanuel Milou's avatar
Emmanuel Milou committed
207
 $ fab drush.make
Emmanuel Milou's avatar
Emmanuel Milou committed
208

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

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

Emmanuel Milou's avatar
Emmanuel Milou committed
213
 $ fab drush.archive_dump
214
215
216

* _Generate_ the guide style:

217
 $ fab patternlab.build