Commits (5)
= Changelog
All notable changes to this project will be documented in this file.
This file should respect change log http://keepachangelog.com/[best practices].
This project adheres to http://semver.org/[Semantic Versioning].
== [Unreleased]
=== Added
* Implements Aegir and standard deployments as Fabric tasks
* Allow database restoration
* Simplify and group fabric commands into separate Python modules
* Implements a more logical and readable set of commands
=== Changed
* Implements Drupalizer a Python module
=== Deprecated
* Almost every commands ... Run `fab --list` !
* Change configuration file syntax
= Installation
SFL Drupal Team <drupal@lists.savoirfairelinux.net>
v2.0.0, 2016-04-05
:toc:
// Refs
:doc-docker: https://www.docker.com/
:doc-fabric: http://www.fabfile.org/
:doc-docker-installation: https://docs.docker.com/engine/installation/
:doc-docker-baseimage: https://hub.docker.com/r/savoirfairelinux/lampd/
:doc-drush: http://docs.drush.org/en/master/
:doc-asciidoctor: http://asciidoctor.org/docs/asciidoc-recommended-practices/
== System Requirements
Drupalizer has been designed to work with Drupal 7
and therefore can not work as a standalone application.
TIP: Whenever it is possible, you should use *Composer* to install and manage the PHP dependencies.
The following dependencies need to be installed:
* {doc-docker}[Docker]
* {doc-fabric}[Fabric]
* {doc-drush}[Drush] (version 6 or 7)
== Installation
CAUTION: The installation procedure to set-up Docker is not described here. Please refer to the official documentation on how to install {doc-docker-installation}[Docker Engine]. The Docker image is based on our {doc-docker-baseimage}[Docker base image], that will automatically installed at setup.
For Fabric to detect Drupalizer as Python module, clone the repository in a directory called `fabfile`.
To test the installation, run:
fab --list
Then, copy and, optionally, edit your local configuration file:
$ cp fabfile/default_vars.py fabfile/local_vars.py
You are now ready to build your Drupal site:
$ fab init
== About this document
This document uses the Asciidoc syntax generator.
It is a convenient tool allowing to write documentation in raw text files, and convert them to HTML or PDF later on.
Visit https://github.com/asciidoctor[Asciidoctor @ *GitHub*] for more informations.
The {doc-asciidoctor}[AsciiDoc Recommanded Practices] is also recommanded.
To generate a HTML version, first install asciidoctor package on your Linux distribution, then issue following command:
$ asciidoctor README.adoc
The README.html is generated in the current directory.
Asciidoctor provides a native PDF renderer for Asciidoc. Still in alpha, but worth the try. Please follow the instructions on the official documentation to
install it, then issue following command:
$ asciidoctor-pdf README.adoc
The README.pdf file shall be created in the current directory.
// This document is included in every project that submodules it.
= README
=== Drupalizer tasks
= 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_
|If False, no prompt. Useful for Jenkins.
|_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_.
|===
=== 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
*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.
TIP: Drupalizer is configured as a git submodule for every project that needs to use it.
TIP: Drupalizer should be configured as a git submodule for every project that needs to use it.
For a complete overview of all available commands, run:
......@@ -14,7 +129,7 @@ To get a more nested or tree-like view, pass the following option:
$ fab --list-format=nested --list
==== Top-level tasks
== Top-level tasks
The top-levels tasks are larger tasks that include others. They are the most commonly called tasks.
......@@ -26,10 +141,15 @@ The top-levels tasks are larger tasks that include others. They are the most com
$ fab install
* _Update_ the Drupal installation
CAUTION: This command will wipe all the modifications made in the working directories.
* _Update_ the Drupal installation
$ fab update
CAUTION: This command may wipe the modifications made in the working directories.
* _Configure_ and _run_ the Behat tests:
$ fab test
......@@ -37,7 +157,7 @@ The top-levels tasks are larger tasks that include others. They are the most com
TIP: The formatters used are _pretty_ and _junit_.
==== Other common tasks
== Other common tasks
Some more atomic tasks supported by *Drupalizer* would be:
......
......@@ -165,12 +165,12 @@ def gen_doc(role='docker'):
:param role Default 'role' where to run the task
"""
if os.path.isfile('{}/README.adoc'.format(env.docker_workspace)):
if h.fab_exists(role, '{}/README.adoc'.format(env.docker_workspace)):
h.fab_run(role, 'asciidoctor -b html5 -o {}/README.html {}/README.adoc'.format(env.docker_workspace,
env.docker_workspace))
print(green('README.html generated in {}'.format(env.docker_workspace)))
if os.path.isfile('{}/CHANGELOG.adoc'.format(env.docker_workspace)):
if h.fab_exists(role, '{}/CHANGELOG.adoc'.format(env.docker_workspace)):
h.fab_run(role, 'asciidoctor -b html5 -o {}/CHANGELOG.html {}/CHANGELOG.adoc'.format(env.docker_workspace,
env.docker_workspace))
print(green('CHANGELOG.html generated in {}'.format(env.docker_workspace)))