README.adoc 4.72 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_
91
|Translation files that must be downloaded when building Drupal and activated during installation (separate with comma). Default: _fr_.
Philippe Mouchel's avatar
Philippe Mouchel committed
92

Emmanuel Milou's avatar
Emmanuel Milou committed
93
94
|===

95
96
97
98
99
100
101
102
103
104
=== Patternlab settings

|===
|Parameters |Description

|_patternlab_dir_
|The Patternlab directory. Default: _empty_

|===

Emmanuel Milou's avatar
Emmanuel Milou committed
105
106
107
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
=== 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
133
134
135

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

For a complete overview of all available commands, run:

 $ fab --list

Emmanuel Milou's avatar
Emmanuel Milou committed
142
143
144
145
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
146
== Top-level tasks
Emmanuel Milou's avatar
Emmanuel Milou committed
147

Emmanuel Milou's avatar
Emmanuel Milou committed
148
The top-levels tasks are larger tasks that include others. They are the most commonly called tasks.
Emmanuel Milou's avatar
Emmanuel Milou committed
149
150
151

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

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

Emmanuel Milou's avatar
Emmanuel Milou committed
154
* _Run_ the Drupal installation
Emmanuel Milou's avatar
Emmanuel Milou committed
155

Emmanuel Milou's avatar
Emmanuel Milou committed
156
 $ fab install
Emmanuel Milou's avatar
Emmanuel Milou committed
157

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

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

Emmanuel Milou's avatar
Emmanuel Milou committed
162
  $ fab update
Emmanuel Milou's avatar
Emmanuel Milou committed
163

Emmanuel Milou's avatar
Emmanuel Milou committed
164
165
166
CAUTION: This command may wipe the modifications made in the working directories.


Emmanuel Milou's avatar
Emmanuel Milou committed
167
 * _Configure_ and _run_ the Behat tests:
Emmanuel Milou's avatar
Emmanuel Milou committed
168

Emmanuel Milou's avatar
Emmanuel Milou committed
169
 $ fab test
Emmanuel Milou's avatar
Emmanuel Milou committed
170

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

173
174
175
176
177
178
179
180
* _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

181
 $ fab --set=build_number=1,migrate=true,remove_platform=true deploy:dev
182

183
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
184

Emmanuel Milou's avatar
Emmanuel Milou committed
185
== Other common tasks
Emmanuel Milou's avatar
Emmanuel Milou committed
186
187

Some more atomic tasks supported by *Drupalizer* would be:
Emmanuel Milou's avatar
Emmanuel Milou committed
188
189
190

* _Start/stop_ the Docker container:

Emmanuel Milou's avatar
Emmanuel Milou committed
191
192
 $ fab docker.container_start
 $ fab docker.container_stop
Emmanuel Milou's avatar
Emmanuel Milou committed
193

Emmanuel Milou's avatar
Emmanuel Milou committed
194
 * _Bash_ into the Docker container:
Emmanuel Milou's avatar
Emmanuel Milou committed
195

Emmanuel Milou's avatar
Emmanuel Milou committed
196
  $ fab docker.connect
Emmanuel Milou's avatar
Emmanuel Milou committed
197

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

Emmanuel Milou's avatar
Emmanuel Milou committed
200
 $ fab behat.run
Emmanuel Milou's avatar
Emmanuel Milou committed
201

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

Emmanuel Milou's avatar
Emmanuel Milou committed
204
 $ fab drush.make
Emmanuel Milou's avatar
Emmanuel Milou committed
205

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

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

Emmanuel Milou's avatar
Emmanuel Milou committed
210
 $ fab drush.archive_dump
211
212
213
214

* _Generate_ the guide style:

 $ fab patternlab.build