Skip to content
This repository has been archived by the owner on Nov 16, 2021. It is now read-only.

Commit

Permalink
Merge pull request #47 from openeuropa/fix-documentation
Browse files Browse the repository at this point in the history 
OPENEUROPA-0000: Update README documentation.
  • Loading branch information
@brummbar
brummbar authored Sep 27, 2019
2 parents e5ecdd3 + b863669 commit 646b45a
Show file tree
Hide file tree
Showing 2 changed files with 88 additions and 142 deletions.
68 changes: 10 additions & 58 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -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 <dg-name>-<project-id>-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 `<dg-name>-<project-id>-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.
Expand All @@ -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.
162 changes: 78 additions & 84 deletions README.md.dist
View file
Original file line number Diff line number Diff line change
@@ -1,149 +1,143 @@
# 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
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

0 comments on commit 646b45a

Please sign in to comment.