diff --git a/README.md b/README.md index d91b801..fd1cb84 100644 --- a/README.md +++ b/README.md @@ -1,40 +1,25 @@ -# OpenEuropa template for Drupal projects - -This is based on [drupal-composer/drupal-project](https://github.com/drupal-composer/drupal-project). +# OpenEuropa template for Drupal 8 projects [![Build Status](https://drone.fpfis.eu/api/badges/openeuropa/drupal-site-template/status.svg?branch=master)](https://drone.fpfis.eu/openeuropa/drupal-site-template) -This project template provides a starter kit for creating a website using the -OpenEuropa Drupal 8 platform. It will install the [OpenEuropa Profile](https://github.com/openeuropa/oe_profile) -which is a lightweight installation profile that includes the minimal number -of modules that are required to enable the [OpenEuropa Theme](https://github.com/openeuropa/oe_theme). -Using this theme will ensure that the project complies with the guidelines for -[European Component Library](https://github.com/ec-europa/europa-component-library). - -In order to build the functionality of the website you are free to use any of the -[OpenEuropa components](https://github.com/openeuropa/openeuropa/blob/master/docs/openeuropa-components.md). - -## Prerequisites +**Please note:** this repository contains code that is necessary to generate +a new Drupal 8 project, please read carefully the [Start a new project](#start-a-new-project) +section below before proceeding. You need to have the following software installed on your local development environment: -* [Composer](https://getcomposer.org/doc/00-intro.md#installation-linux-unix-osx). +* [Composer](https://getcomposer.org/doc/00-intro.md#installation-linux-unix-osx) * [Docker Compose](https://docs.docker.com/compose/install/) +* PHP 7.1 or greater (only needed during project creation) -## Create the project +## Start a new project -The project is built using [Composer create-project](https://getcomposer.org/doc/03-cli.md#create-project). -This is the equivalent of doing a `git clone` followed by a `composer install`. - -One does not need to be in this repository in order to use the `composer create-project` command. -The project can be created using the following command: +To create a new Drupal 8 project run the following command: ```bash composer create-project openeuropa/drupal-site-template --stability=dev --reference ``` -For local development, to test the Setup Wizard, run `composer setup` from the root of this project. - This will download the starterkit into the `--reference` folder and a wizard will ask you for the project name and your organisation. It will use this information to personalize your project's configuration files. @@ -44,38 +29,5 @@ takes several minutes. At the end you will be asked whether to remove the existing version history. It is recommended to confirm this question so that you can start your project with a clean slate. -After installing the dependencies, install a clean installation of your site, using the following command: - -```bash -./vendor/bin/run toolkit:install-clean -``` - -Using default configuration, the development site files should be available in the `build` directory. - -Before to commit your project on your repository, export the configuration on `config/sync` -using the following command:. - -```bash -./vendor/bin/drush cex -``` - -## Drone - -A `.drone.yml` file is provided for running CI tests on Drone. Further details of how to set this up can be found in the - [drone documentation](https://docs.drone.io/). - -## Project management - -It is recommended that the version of `oe_theme` is locked to the current minor version before going live with the -project, so that updates to the theme do not cause problems to a running site. We recommend that this is periodically -updated to the latest version, after doing manual testing. - -A separate `.gitignore` file is provided which is used for the project. Drupal scaffold files should be committed after -running composer install or update. See the -[Drupal scaffold documentation](https://github.com/drupal-composer/drupal-scaffold/blob/master/README.md#limitation) -for further details. - -Further details of how to build sites, install Drupal and run tests can be found in the `README.md` found within your site - folder. - -Now you are ready to push your project to your chosen code hosting service. +The following steps to get your new site up and running can be found in the +`README.md` inside your newly created project folder. diff --git a/README.md.dist b/README.md.dist index b69d05c..48ba5d1 100644 --- a/README.md.dist +++ b/README.md.dist @@ -1,85 +1,71 @@ # OpenEuropa Drupal project. -This project starter kit will create a website using the -OpenEuropa Drupal 8 platform. It will install the [OpenEuropa Profile](https://github.com/openeuropa/oe_profile) -which is a lightweight installation profile that includes the minimal number -of modules that are required to enable the [OpenEuropa Theme](https://github.com/openeuropa/oe_theme). -Using this theme will ensure that the project complies with the guidelines for -[European Component Library](https://github.com/ec-europa/europa-component-library). +This project starter kit will create a website using +[OpenEuropa components](https://github.com/openeuropa/documentation/blob/master/docs/openeuropa-components.md). +It will install only two components: + +- [The OpenEuropa Profile](https://github.com/openeuropa/oe_profile): + a lightweight Drupal installation profile that includes the minimal number of + modules to help get your started +- [The OpenEuropa Theme](https://github.com/openeuropa/oe_theme): the official + Drupal 8 theme of the European Commission which will ensure that the project + complies with the [European Component Library](https://github.com/ec-europa/europa-component-library) + guidelines. In order to build the functionality of the website you are free to use any of the [OpenEuropa components](https://github.com/openeuropa/openeuropa/blob/master/docs/openeuropa-components.md). -Starting a new project is a 4 step procedure: - -## 1. Prerequisites +## Prerequisites You need to have the following software installed on your local development environment: -* [Composer](https://getcomposer.org/doc/00-intro.md#installation-linux-unix-osx). * [Docker Compose](https://docs.docker.com/compose/install/) -## 2. Configuration +Having the following installed locally is also recommended, but not mandatory: + +* PHP 7.1 or greater +* [Composer](https://getcomposer.org/doc/00-intro.md#installation-linux-unix-osx). + +**Please be aware:** the OpenEuropa team will only address support requests +if you use the provided `docker-compose.yml`. -The project ships with default configuration that is intended to run the -website on the Docker containers we provide. If you are content with using -these, you can skip directly to step 3. +## Configuration -If you want to run the website using your locally installed LAMP stack, you -will want to change the configuration to match your local system. +The project ships with default setup configuration that is intended to run the +website on the Docker containers we provide. -Customize the default configuration values by copying `runner.yml.dist` to -`runner.yml`: +To customize the default configuration values copy `runner.yml.dist` to `runner.yml`: ```bash cp runner.yml.dist runner.yml ``` -Now edit `runner.yml` with your most beloved text editor. You will want to set -the database host to `localhost`, and provide the correct database name and -credentials. Also update the `base_url` and Selenium path to match your local -environment. +Now edit `runner.yml` with your most beloved text editor and change setup +configuration as needed. -## 3. Installation +## Site build and installation -### 3.1. Using Docker +The shipped `docker-compose.yml` file provides the necessary services and tools +to install, run and test an OpenEuropa Drupal 8 site. -You can build a development site using [Docker](https://www.docker.com/get-docker) and -[Docker Compose](https://docs.docker.com/compose/) with the provided configuration. +By default, Docker Compose reads two files, a `docker-compose.yml` and an +optional `docker-compose.override.yml` file. By convention, the `docker-compose.yml` +contains your base configuration. The override file, as its name implies, +can contain configuration overrides for existing services or entirely new services. -Docker provides the necessary services and tools such as a web server and a database server to get the site running, -regardless of your local host configuration. - -#### Requirements: - -- [Docker](https://www.docker.com/get-docker) -- [Docker Compose](https://docs.docker.com/compose/) - -#### Configuration - -By default, Docker Compose reads two files, a `docker-compose.yml` and an optional `docker-compose.override.yml` file. -By convention, the `docker-compose.yml` contains your base configuration and it's provided by default. -The override file, as its name implies, can contain configuration overrides for existing services or entirely new -services. If a service is defined in both files, Docker Compose merges the configurations. -Find more information on Docker Compose extension mechanism on [the official Docker Compose documentation](https://docs.docker.com/compose/extends/). - -#### Usage +Find more information on Docker Compose extension mechanism on +[the official Docker Compose documentation](https://docs.docker.com/compose/extends/). To start, run: -```bash -docker-compose up -``` - -It's advised to not daemonize `docker-compose` so you can turn it off (`CTRL+C`) quickly when you're done working. -However, if you'd like to daemonize it, you have to add the flag `-d`: - ```bash docker-compose up -d ``` +This will run the Docker containers in the background, i.e. it will "daemonize" them. + Then: ```bash @@ -87,63 +73,71 @@ docker-compose exec web composer install docker-compose exec web ./vendor/bin/run toolkit:install-clean ``` -Using default configuration, the development site files should be available in the `build` directory and the development site -should be available at: [http://127.0.0.1:8080/build](http://127.0.0.1:8080/build). +The site build will be available in the `web` directory and the site itself +will be reachable at: [http://localhost:8080/web](http://localhost:8080/web). -#### Running the tests - -To run the grumphp checks: +Before to commit your project on your repository, export the configuration on `config/sync` +using the following command: ```bash -docker-compose exec web ./vendor/bin/grumphp run +docker-compose exec web ./vendor/bin/drush cex ``` -To run the phpunit tests: +## Commit and push -```bash -docker-compose exec web ./vendor/bin/phpunit -``` +The final step is to have a new git repository and commit all the files. A +`.gitignore` file is provided to ensure you only commit your own project files. -To run the behat tests: +If you have not been already provided with one please contact your management +and/or the Quality Assurance team. ```bash -docker-compose exec web ./vendor/bin/behat +git init +git add . +git commit -m "Initial commit." ``` -### 3.2. Using a local LAMP stack +Now you are ready to push your project to your chosen code hosting service. + +## Running the tests -Install the website using the task runner: +To run the coding standards and other static checks: ```bash -./vendor/bin/run drupal:site-install +docker-compose exec web ./vendor/bin/grumphp run ``` -The site will be available through your local web server. - -To verify whether everything works as expected, you can run the example Behat -test suite: +To run Behat tests: ```bash -./vendor/bin/behat +docker-compose exec web ./vendor/bin/behat ``` -## 4. Commit and push +## Continuous integration and deployment -The final step is to create a new git repository and commit all the files. A -`.gitignore` file is provided to ensure you only commit your own project files. +To check the status of the continuous integration of your project, go to [Drone](https://drone.fpfis.eu/). -```bash -git init -git add . -git commit -m "Initial commit." -``` +A pipeline - created and maintained by DevOps - is applied by default. +It manages the code review of the code, it runs all tests on the repository and +builds the site artifact for the deployment. -Now you are ready to push your project to your chosen code hosting service. +You can control which commands will be ran during deployment by creating +and pushing a `.opts.yml` file. -## 4. CI on Drone +If none is found the following one will be ran: + +```yml +upgrade_commands: + - './vendor/bin/drush state:set system.maintenance_mode 1 --input-format=integer -y' + - './vendor/bin/drush updatedb -y' + - './vendor/bin/drush cache:rebuild' + - './vendor/bin/drush state:set system.maintenance_mode 0 --input-format=integer -y' + - './vendor/bin/drush cache:rebuild' +``` -To check the status of the continuous integration of your project, go to [Drone] (https://drone.fpfis.eu/). +The following conventions apply: -A pipeline - created and maintained by devops - is applied by default. It manages the code review of the code, -runs all the business tests on the repository and builds the site artifact for the deployment. -Customizing this pipeline is possible by adding a custom ".drone.yml" file to the project's root folder. +- Every push on the site's deployment branch (usually `master`) will trigger + a deployment on the acceptance environment +- Every new tag on the site's deployment branch (usually `master`) will + trigger a deployment on production