Platform for Experimental and Collaborative Ethnography (PECE)

PECE is a Free and Open Source (Drupal-based) digital platform that supports multi-sited, cross-scale ethnographic and historical research. PECE is built as a Drupal distribution to be improved and extended like any other Drupal project.

This repository contains the development code for PECE. It has work in progress which is intended to be used by developers to suggest bug fixes and improvements, as well as a starting point for customizations of the platform. If you are a developer wishing to contribute to the development process, this is the repository you must use.

If you are an end-user looking for stable PECE releases, please access the repository PECE-distro, which contains our installation package with the latest stable version. If you have general questions about the platform, please refer to our complete documentation.

Prerequisites

PECE development is made easy by using the following software projects:

• Node.js JavaScript runtime;
• Gulp task runner;
• Drush command line interface;
• Kraftwagen Drush extension;
• Drupal.

Keep in mind that these are prerequisites for the development environment of the PECE project, not for the end-user software. In other words, you will not need to follow these instructions if you are only interested in installing and running PECE. Please, refer to our official documentation if you are looking for instructions for regular PECE installation and usage.

Find more information on how to run PECE development environment with Docker at the end of this file.

Installing Node.js

We strongly suggest you to use nvm to install Node.js on your development machine. You must have Node.js version 4.x.x and npm version 3.x.x, at least.

1. To install nvm run the following on you terminal:

curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.31.0/install.sh | bash

After doing so, you will probably have to open a new terminal to have nvm available as a command. Visit nvm's official installation guide if you have any questions.

2. To install Node.js version 4.x.x run the following on you terminal:

nvm install 4.x.x
nvm use 4.x.x

Alternatively, you can first clone this repository, change to it's directory, and run nvm install. The file ``.nvmrc` will inform nvm which version of Node.js it should install and automatically set it as currently version to use.

3. To install the required version of npm you must run the following on your terminal:

npm install -g npm@3.x.x

To check if everything went smoothly, run the following on your terminal:

node --version # should echo a number starting with 4
npm --version # should echo a number starting with 3

Installing Gulp

Even though Gulp is not a hard requirement for installing PECE's development version, it is currently the main tool for running common tasks which are inconvenient if not automated. We strongly suggest you install it to ease installation process and avoid mistakes. Keep in mind that the following Getting started guide will use Gulp. Consider having a look at the full list of the available tasks.

Gulp is a Node.js package that provides an executable, and can be easily installed with the following command:

npm install -g gulp

After doing that, gulp command should be available in your terminal. If you find any trouble, please refer to Gulp's official installation guide.

Installing Drush

To properly install Drush please follow the official installing guide.

Installing Kraftwagen

Kraftwagen also provides an official installation guide. Unfortunutelly, we currently use a forked version of the project. You can still follow the instructions on the official installation guide, but the git clone should come from Taller's fork, on the local_workflow_improvements branch.

Terminal steps to install:

1. Move to Drush install directory.

cd ~/.drush

2. Clone the Taller fork version of Kraftwagen.

git clone -b local_workflow_improvements --single-branch git://github.com/TallerWebSolutions/kraftwagen.git

3. Make Drush knows you've installed a new module.

drush cc drush

Using Kraftwagen is an important part of the build process. Please make sure you understand its concepts before proceding to the next steps.

Getting Started

If you follow these instructions you will get a copy of the project up and running on your local machine for development and testing purposes. Proceed to the Deployment to learn how to deploy the project on a live system.

Download

To download the project, simply clone it to your directory of choice as follows:

git clone git://github.com/PECE-project/drupal-pece.git
cd drupal-pece

Installing dependencies

PECE dependends on a bunch of Node.js packages, which will mostly help building PECE, and Bower packages, which refer to the front-end libraries we use. To install all of these dependencies you can run the following command:

npm install

After installing Node.js dependencies, npm will automatically perform Bower 'install'.

Build

Kraftwagen - the tool behind PECE building system - relies on the concept of different environments upon building. The two environments in use are:

• production
• development

In the Drupal installation process, the environment config will be responsible for enabling/disabling specific modules. Furthermore, using the development environment will also cause for the directory structure to use the src directory, using pece Drupal profile, inside Drupal's root directory - this means that you can actively engage development using this directory without having to build every time you change something. This technique was introduced as a pull-request to the Kraftwagen project.

Kraftwagen provides many commands through the drush interface. We encapsulate some of them inside 'gulp tasks' with the intend to ease the building and configuration steps.

1. Setup the Kraftwagen workspace:

gulp setup

You'll then be prompted to define the environment (defaults to production) and the posterior database configuration.

The database configuration provided here is only used to connect to the database, not to create it; prior to proceeding with the install you should make sure to create the database and make it properly available via the settings provided on this step.

2. Download Drupal and contributed modules to build the distro:

gulp build

3. Configure the server

Now you should have the directory build already created as Drupal's root. You should go forward and configure Apache, Nginx, or whichever HTTP server you find best. Remember to point the site's root directory to the build directory, not to the cloned repository's root.

4. Setup permissions

Drupal requires you give permission for the HTTP server user to write to the files directory. This is a crucial step in order to continue the installation process. Pre and post-configuration steps must be taken in order to ensure that proper permissions are set. Please refer to the official Drupal documention on how to properly setup the permissions in your server backend.

5. Installing Drupal

There are currently two methods for installing a new PECE instance: via command-line or using the web browser.

5.1 Using the browser

In your browser, access the url /install.php, preceded with the domain serving the site. The install process is self-explanatory. Keep in mind it takes a while to finish (up to 30 minutes on low-end configuration servers).

5.2 Using the command-line

There is a one-command install available through Gulp. Keep in mind that this command will erase any currently available data on the database configured on step 1. To proceed, run the following:

gulp site-install

If the user running the Gulp task differs from the user which is being used by the web server, you will need to redo step 4 in other to make sure the server has proper permission to manage files.

6. (Optional) Adding demo content

PECE comes with a script to add some testing content. To execute it, run:

gulp demo

Alternatively, you can do it in your browser by accessing Configuration > Development > PECE Demo (or /admin/config/development/pece/demo). This route will only be available if you configured the environment to development or if you enabled pece_demo module.

Running the tests

Requirements

• User: admin
• Passwords: 123456789

It's necessary has an image with the name sf.jpg in the library to use in uploads fields.

npm run cypress:open

Click on the test you want to run.

TODO

Deployment

TODO

Contributing

Contributions should be done using pull requests to this repository. We keep the master branch current with tested, stable code. The branch dev is used for the on-going development tasks, new features, and bug fixes.

Our Contributors' guide contains all the information you will need to know about the project before submitting your contribution. Please read it before sending us pull requests.

Authors

Our official documentation contains the information on authorship for the design and implementation tasks of the platform. Please check the document PECE Team for more information.

License

All the code produced for PECE is released under the GNU GPL version 3 only. Please, read our legal documents for more information.

PECE Development environment with Docker

---

Requirements

• GIT
• Docker Compose

---

Clone project

$ git clone https://github.com/PECE-project/drupal-pece.git
$ cd drupal-pece/

---

Up virtual machine to work

$ make run

• Access url http://localhost:8080
• For Database configuration:
  • Host: pece-db
  • Database: pece
  • User: pece
• For more Database configuration info, see DOCKER.md file