+
+
+
+
+
+
📁 Archived — Drupal 7 Legacy Documentation
+ This page contains the original PECE installation instructions for
Drupal 7, which is no longer maintained.
+ If you are setting up a new PECE instance, please use the
+
current installation guide (Drupal 11+) instead.
+
+
+
+
PECE System Administration
+
How do I install PECE?
+
PECE is a Free Software-based Drupal distribution, therefore the
+standard installation procedure for Drupal 7 applies to PECE with a few
+extra dependencies.
+
The following instructions have been tested on a Debian 8 (jessie)
+server, but they are not OS-dependent. PECE should run on any system
+supported by Drupal 7. PECE has been tested in virtual machines with
+256M allocated for PHP, being 128M the recommended minimum for Drupal 7
+distributions. Your configuration, of course, may vary considerably
+depending on the usage you are making of the platform. Refer to our data
+management guidelines under the “sustainability” section to learn about
+the recommended minimum specs for your servers.
+
Downloading the Distro
+
Our distribution is currently being developed on Github. You can obtain
+the most updated version following the link “Releases” on the project’s
+git repository:
+
+https://github.com/PECE-project/pece-distro
+
+
Alternatively, you can obtain the source code and build the distro
+yourself if you intend to help our team by fixing bugs and extending the
+platform for your research purposes:
+
+git clone
+https://github.com/PECE-project/drupal-pece.git
+
+
If you are a developer who wants to contribute to PECE, you will need to
+follow special instructions to install and configure the tools for
+building the distro. Consult the sub-section Setting up the Development Environment
+below for more information.
+
Dependencies
+
PECE has extra dependencies in addition to the ones you will need for
+Drupal 7 core:
+
+-
+
cURL
+
+-
+
php-mcrypt (for AES encryption support in backups and user passwords)
+
+-
+
php-ssh2 (for backup SFTP support, installed via PHP pear)
+
+-
+
pecl-yaml (for YAML parsing)
+
+
+
Quick Install
+
If you have the server backend already set-up, you can quickly install
+PECE following these steps:
+
Clone the ‘’pece-distro’’ repository:
+
+git clone
+https://github.com/PECE-project/pece-distro.git
+
+
Create an empty database:
+
+mysql -u $YOUR_USER -p -e "CREATE DATABASE $YOUR_DB_NAME
+CHARACTER SET utf8 COLLATE utf8_general_ci;"
+
+
Proceed to the URL in which your Drupal will reside, i.e.
+https://worldpece.org. From there, you can install PECE like any other
+Drupal site. Follow the Drupal.org official documentation if you need further help. In the
+section Troubleshooting below we describe common issues users have when trying to install PECE without the proper backend dependencies, configurations, and permissions.
+
One important note: please, make sure to set the permissions on the
+filesystem properly. We cannot emphasize this enough. The official Drupal documentation explains how
+to do so, if you have questions. (In our experience, we have needed to
+set the file permissions at sites/default/files/artifacts to 770 and
+sites/default/files/private to 770.)
+
I want to use HTTPS with PECE. How can I do that?
+
A very simple tutorial for setting up HTTPS with Certbot on Ubuntu can be found here.
+
I’ve installed PECE, but none of my links are working. What is going on?
+
Your webserver is not properly configured to support what is called
+“Clean URLs” on Drupal. Make sure you have your httpd “rewrite” rules
+properly set-up. This configuration can be done in the vhost file of
+your nginx configuration, following the Perusio guide or using the default.htaccess file that is provided by default by Drupal if you are running Apache.
+
I get an error about a YAML parser being missing. How can I fix that?
+
Newer versions of PHP require you to install pecl-yaml for YAML parsing. You can find it here.
+We recommend using the latest version, which is 2.0.4 at the time of writing. Follow the pecl-yaml instructions to build and install it.
+Then edit your php.ini file. For example, if you are using PHP 7.2, the file will be found at:
+/etc/php/7.2/apache2/php.ini
+
Add the following line to php.ini:
+extension=yaml.so
+
When should the admin login credentials be used?
+
Distribute admin login credentials to as few users as possible. Admin
+login credentials should only be used to configure settings and to
+approve new users. The admin credentials should not be used to add
+content or comment on content.
+
+
Go to “Administration » Configuration » System » Site information” and
+fill out the information about your site name, the basic admin password,
+contact, timezone and other relevant info.
+
How do I upload the terms of service?
+
Go to “Administration » Configuration » People » Legal” and click “Add
+T&C”, then fill-out the boxes with your custom text to be displayed to
+every user who requests an account on the system.
+
How do I set up back-ups?
+
As explained in our data management guidelines, PECE is configured to
+automatically generate backups. You should, however, revise the settings
+and set-up a SFTP connection to transfer your backup to another server
+and ensure that you have extra security when storing your encrypted
+backups. First, revise the settings we provided, changing whatever you
+think is needed (say, the most convenient time, when the site is not
+being used, to generate the backup). Go to “Configuration » System »
+Backup and Migrate” to perform this first step. Then, click on
+“Destinations” and “Add Destination” to set-up the SFTP connection with
+the credentials of your backup server. Please note that you have to use
+the port 22 (not 21) and password authentication, since ssh-key
+authentication is unfortunately not supported yet.
+
+
PECE uses Drupal notification for key events on the system. It has to be
+configured using a regular email address, provided you have all the mail
+server information. You just need your SMTP server info and credentials
+to get this done. Go to “Administration » Configuration » System » SMTP
+Authentication Support” and provide your SMTP server information,
+including username and password.
+
How do I increase the file upload limit?
+
While logged-in as an administrator, navigate to Administration >>
+Configuration >> Media >> File Settings. Under the Maximum
+Upload Size field, enter a new value (we use 2GB). Click Save
+Configuration. You may also need to increase the upload limit on the
+server.
+
How do I update my instance when a new version of the PECE distro is released?
+
Always back-up your files and database before updating the platform.
+
Put the site in maintenance mode. Under sites/default/, there is a file
+called settings.php. Search for $update_free_access = FALSE; and
+change FALSE to TRUE.
+
Then, go to YourSite/update.php and follow the steps. In theory major
+updates are not handled differently, but sometimes issues have occurred.
+
Be sure to turn off maintenance mode when you are done.
+
Other Post-Installation Troubleshooting
+
+-
+
“Time Out” during installation: this issue is related to the usage of Drupal distributions in “shared hosting” environments which are very limited in terms of the resources allocated per client / user account. If the installation process is interrupted before it is finished, you will have to check your PHP configuration and increase the memory allocation and timeout configuration for the php scripts with the following directives: memory_limit and max_execution_time which can be found in your php.ini file. After doing so, you should not experience more “timeouts” during installation.
+
+-
+
Links do not work: your webserver is not properly configured to support what is called “Clean URLs” on Drupal. Make sure you have your httpd “rewrite” rules properly set-up. This configuration can be done in the vhost file of your nginx configuration, following the Perusio guide or using the default.htaccess file that is provided by default by Drupal if you are running Apache.
+
+-
+
Permission denied when uploading content: your filesystem permissions must be set accordingly for the public and private directories, since PECE uses both extensively. Follow this official Drupal tutorial to configure the permissions properly for both directories where you installed PECE.
+
+-
+
Permission denied when uploading content after configuring filesystem permissions: make sure your /tmp is also writable and, if you are on a shared host and cannot have access to it, configure Drupal to point to a temporary directory in your system/files path. There is a discussion about this issue on Drupal.org that is helpful.
+
+-
+
Cannot create users, server internal error: in our experience, php5-mcrypt is probably not installed in your system. Make sure it is properly installed and loaded, by running php -m in a shell and checking if it is listed.
+
+
+
+
+
+
+
ℹ️ Drupal 11+ Documentation
+ This page covers installation and administration of PECE on
Drupal 11 (PECE 2.x).
+ If you are running an older PECE instance on
Drupal 7, the
+
legacy installation guide (Drupal 7) has been archived for reference.
+
+
PECE System Administration
How do I install PECE?
PECE is a Free Software-based Drupal distribution, therefore the
-standard installation procedure for Drupal 7 applies to PECE with a few
-extra dependencies.
-
The following instructions have been tested on a Debian 8 (jessie)
-server, but they are not OS-dependent. PECE should run on any system
-supported by Drupal 7. PECE has been tested in virtual machines with
-256M allocated for PHP, being 128M the recommended minimum for Drupal 7
-distributions. Your configuration, of course, may vary considerably
-depending on the usage you are making of the platform. Refer to our data
-management guidelines under the “sustainability” section to learn about
-the recommended minimum specs for your servers.
+
standard installation procedure for Drupal applies to PECE with a few
+extra dependencies. PECE now runs on Drupal 11 and requires a modern server stack.
+
The following instructions have been tested on Debian 11 (Bullseye) and Debian 12 (Bookworm)
+servers, but they are not OS-dependent. PECE should run on any system
+supported by Drupal 11. A minimum of 256 MB of PHP memory is recommended;
+your configuration may vary considerably depending on the usage and content
+volume of your platform. Refer to our data management guidelines under the
+"sustainability" section to learn about the recommended minimum specs for
+your servers.
+
System Requirements
+
PECE 2.x (Drupal 11) requires the following minimum versions:
+
+PHP: 8.1 or higher (8.3 recommended). Required extensions: curl, gd, json, mbstring, openssl, pdo, xml, zip.
Database (one of the following):
+
+- MySQL 8.0.17+ or MariaDB 10.6.0+
+- PostgreSQL 16.0+
+- SQLite 3.45+
+
+Web server: Apache 2.4+ (with mod_rewrite enabled) or Nginx 1.1+.
Composer 2.x — required for dependency management.
Drush 13+ — recommended for command-line administration and updates.
+
For the full, up-to-date list of Drupal 11 system requirements, see the
+official Drupal system requirements page.
Downloading the Distro
-
Our distribution is currently being developed on Github. You can obtain
-the most updated version following the link “Releases” on the project’s
-git repository:
+
Our distribution is developed on GitHub. You can obtain the most recent
+version by visiting the project's repository:
-https://github.com/PECE-project/pece-distro
+https://github.com/PECE-project/drupal-pece
-
Alternatively, you can obtain the source code and build the distro
-yourself if you intend to help our team by fixing bugs and extending the
-platform for your research purposes:
+
To install PECE using Composer (recommended), run:
-git clone
-https://github.com/PECE-project/drupal-pece.git
+composer create-project pece/pece-distro YOUR_PROJECT_NAME
-
If you are a developer who wants to contribute to PECE, you will need to
-follow special instructions to install and configure the tools for
-building the distro. Consult the sub-section Setting up the Development Environment
-below for more information.
+
Alternatively, you can clone the repository directly if you intend to
+contribute bug fixes or extend the platform for your research purposes:
+
+git clone https://github.com/PECE-project/drupal-pece.git
+
+
If you are a developer who wants to contribute to PECE, consult the
+Contributing Guide
+in the repository for instructions on setting up a local development environment.
Dependencies
-
PECE has extra dependencies in addition to the ones you will need for
-Drupal 7 core:
+
PECE manages its PHP dependencies via Composer. After cloning or creating
+the project, install all dependencies by running:
+
+composer install
+
+
Key server-side requirements beyond Drupal 11 core include:
-
-
cURL
-
--
-
php-mcrypt (for AES encryption support in backups and user passwords)
+cURL — required for outbound HTTP requests.
-
-
php-ssh2 (for backup SFTP support, installed via PHP pear)
+php-ssh2 — optional; needed for SFTP-based backup destinations.
-
-
pecl-yaml (for YAML parsing)
+Composer 2.x — required for dependency management and site updates.
+
Note: php-mcrypt is no longer required. It was removed from PHP 7.2+
+and is not needed by Drupal 11 or PECE 2.x.
Quick Install
-
If you have the server backend already set-up, you can quickly install
-PECE following these steps:
-
Clone the ‘’pece-distro’’ repository:
+
If your server stack (PHP 8.1+, a supported database, and a web server)
+is already set up, you can install PECE with the following steps:
+
1. Create the project with Composer:
-git clone
-https://github.com/PECE-project/pece-distro.git
+composer create-project pece/pece-distro YOUR_PROJECT_NAME
+cd YOUR_PROJECT_NAME
-
Create an empty database:
+
2. Create an empty database:
-mysql -u $YOUR_USER -p -e "CREATE DATABASE $YOUR_DB_NAME
-CHARACTER SET utf8 COLLATE utf8_general_ci;"
+mysql -u $YOUR_USER -p -e "CREATE DATABASE $YOUR_DB_NAME CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
-
Proceed to the URL in which your Drupal will reside, i.e.
-https://worldpece.org. From there, you can install PECE like any other
-Drupal site. Follow the Drupal.org official documentation if you need further help. In the
-section Troubleshooting below we describe common issues users have when trying to install PECE without the proper backend dependencies, configurations, and permissions.
-
One important note: please, make sure to set the permissions on the
-filesystem properly. We cannot emphasize this enough. The official Drupal documentation explains how
-to do so, if you have questions. (In our experience, we have needed to
-set the file permissions at sites/default/files/artifacts to 770 and
-sites/default/files/private to 770.)
+
3. Run the Drupal installer by navigating to the URL where your site will
+reside (e.g. https://worldpece.org) and following the on-screen steps,
+or use Drush for a non-interactive install:
+
+drush site:install --db-url=mysql://USER:PASS@localhost/DB_NAME --account-name=admin --account-pass=CHANGEME
+
+
Follow the official Drupal installation documentation
+if you need further help. The Troubleshooting
+section below describes common issues encountered when the backend
+dependencies, configuration, or filesystem permissions are not correct.
+
One important note: please make sure to set the permissions on the
+filesystem properly. The official Drupal security documentation explains
+how to do so. In our experience, the following directories need to be
+writable by the web server:
+
+web/sites/default/files (public files) — permissions 755 or 775web/sites/default/files/private (private files) — permissions 750 or 770
I want to use HTTPS with PECE. How can I do that?
-
A very simple tutorial for setting up HTTPS with Certbot on Ubuntu can be found here.
-
I’ve installed PECE, but none of my links are working. What is going on?
-
Your webserver is not properly configured to support what is called
-“Clean URLs” on Drupal. Make sure you have your httpd “rewrite” rules
-properly set-up. This configuration can be done in the vhost file of
-your nginx configuration, following the Perusio guide or using the default.htaccess file that is provided by default by Drupal if you are running Apache.
-
I get an error about a YAML parser being missing. How can I fix that?
-
Newer versions of PHP require you to install pecl-yaml for YAML parsing. You can find it here.
-We recommend using the latest version, which is 2.0.4 at the time of writing. Follow the pecl-yaml instructions to build and install it.
-Then edit your php.ini file. For example, if you are using PHP 7.2, the file will be found at:
-/etc/php/7.2/apache2/php.ini
-
Add the following line to php.ini:
-extension=yaml.so
+
A simple tutorial for setting up HTTPS with Certbot (Let's Encrypt) on Ubuntu or Debian can be found
+on the official Certbot website.
+Select your web server and operating system to get tailored instructions.
+
I've installed PECE, but none of my links are working. What is going on?
+
Your web server is not properly configured to support URL routing for Drupal.
+Make sure the rewrite module is enabled and your virtual host is configured
+to allow .htaccess overrides (AllowOverride All). For Apache, Drupal ships
+with a .htaccess file in the web/ directory that handles URL rewriting
+automatically. For Nginx, follow the
+Drupal.org Nginx configuration guide.
When should the admin login credentials be used?
Distribute admin login credentials to as few users as possible. Admin
login credentials should only be used to configure settings and to
approve new users. The admin credentials should not be used to add
content or comment on content.
-
Go to “Administration » Configuration » System » Site information” and
-fill out the information about your site name, the basic admin password,
+
Go to Administration → Configuration → System → Basic site settings and
+fill out the information about your site name, email address,
contact, timezone and other relevant info.
How do I upload the terms of service?
-
Go to “Administration » Configuration » People » Legal” and click “Add
-T&C”, then fill-out the boxes with your custom text to be displayed to
-every user who requests an account on the system.
+
Go to Administration → Configuration → People → Legal and click "Add
+T&C", then fill out the boxes with your custom text to be displayed to
+every user who requests an account on the system.
How do I set up back-ups?
As explained in our data management guidelines, PECE is configured to
automatically generate backups. You should, however, revise the settings
-and set-up a SFTP connection to transfer your backup to another server
-and ensure that you have extra security when storing your encrypted
-backups. First, revise the settings we provided, changing whatever you
-think is needed (say, the most convenient time, when the site is not
-being used, to generate the backup). Go to “Configuration » System »
-Backup and Migrate” to perform this first step. Then, click on
-“Destinations” and “Add Destination” to set-up the SFTP connection with
-the credentials of your backup server. Please note that you have to use
-the port 22 (not 21) and password authentication, since ssh-key
-authentication is unfortunately not supported yet.
+and set up an SFTP connection to transfer your backup to another server
+to ensure extra security when storing your encrypted backups. Go to
+
Configuration → System → Backup and Migrate to review backup settings.
+Then click
Destinations → Add Destination to configure the SFTP
+connection with the credentials of your backup server. Use port 22 and
+password authentication.
-
PECE uses Drupal notification for key events on the system. It has to be
+
PECE uses Drupal notifications for key events on the system. It has to be
configured using a regular email address, provided you have all the mail
-server information. You just need your SMTP server info and credentials
-to get this done. Go to “Administration » Configuration » System » SMTP
-Authentication Support” and provide your SMTP server information,
+server information. Go to Administration → Configuration → System → SMTP
+Authentication Support and provide your SMTP server information,
including username and password.
How do I increase the file upload limit?
-
While logged-in as an administrator, navigate to Administration >>
-Configuration >> Media >> File Settings. Under the Maximum
-Upload Size field, enter a new value (we use 2GB). Click Save
-Configuration. You may also need to increase the upload limit on the
-server.
+
While logged in as an administrator, navigate to Administration →
+Configuration → Media → File system. Under the Maximum Upload Size
+field, enter a new value (we use 2 GB). Click Save Configuration. You
+may also need to raise upload_max_filesize and post_max_size in your
+php.ini file and restart your web server.
How do I update my instance when a new version of the PECE distro is released?
-
Always back-up your files and database before updating the platform.
-
Put the site in maintenance mode. Under sites/default/, there is a file
-called settings.php. Search for $update_free_access = FALSE; and
-change FALSE to TRUE.
-
Then, go to YourSite/update.php and follow the steps. In theory major
-updates are not handled differently, but sometimes issues have occurred.
-
Be sure to turn off maintenance mode when you are done.
+
Always back up your files and database before updating the platform.
+
Put the site in maintenance mode via Administration → Configuration →
+Development → Maintenance mode, or with Drush:
+
+drush state:set system.maintenance_mode 1 --input-format=integer
+
+
Pull the latest code and update dependencies with Composer:
+
+composer update
+drush updatedb
+drush cache:rebuild
+
+
Disable maintenance mode when done:
+
+drush state:set system.maintenance_mode 0 --input-format=integer
+
+
Refer to the official Drupal upgrade documentation
+for more details on major version upgrades.
Other Post-Installation Troubleshooting
-
-
“Time Out” during installation: this issue is related to the usage of Drupal distributions in “shared hosting” environments which are very limited in terms of the resources allocated per client / user account. If the installation process is interrupted before it is finished, you will have to check your PHP configuration and increase the memory allocation and timeout configuration for the php scripts with the following directives: memory_limit and max_execution_time which can be found in your php.ini file. After doing so, you should not experience more “timeouts” during installation.
-
--
-
Links do not work: your webserver is not properly configured to support what is called “Clean URLs” on Drupal. Make sure you have your httpd “rewrite” rules properly set-up. This configuration can be done in the vhost file of your nginx configuration, following the Perusio guide or using the default.htaccess file that is provided by default by Drupal if you are running Apache.
+Time Out during installation: this issue is related to the usage of Drupal distributions in "shared hosting" environments which are very limited in terms of the resources allocated per client / user account. If the installation process is interrupted before it is finished, you will have to check your PHP configuration and increase the memory allocation and timeout configuration for PHP scripts with the following directives: memory_limit and max_execution_time, found in your php.ini file. After doing so, you should not experience more "timeouts" during installation.
-
-
Permission denied when uploading content: your filesystem permissions must be set accordingly for the public and private directories, since PECE uses both extensively. Follow this official Drupal tutorial to configure the permissions properly for both directories where you installed PECE.
+Links do not work: your web server is not properly configured to support Drupal's URL routing. Make sure your rewrite rules are set up correctly. For Apache, ensure AllowOverride All is set in your virtual host and the .htaccess file in the web/ directory is present. For Nginx, follow the Drupal.org Nginx configuration guide.
-
-
Permission denied when uploading content after configuring filesystem permissions: make sure your /tmp is also writable and, if you are on a shared host and cannot have access to it, configure Drupal to point to a temporary directory in your system/files path. There is a discussion about this issue on Drupal.org that is helpful.
+Permission denied when uploading content: your filesystem permissions must be set correctly for the public and private file directories, since PECE uses both extensively. Follow the official Drupal security documentation to configure permissions properly.
-
-
Cannot create users, server internal error: in our experience, php5-mcrypt is probably not installed in your system. Make sure it is properly installed and loaded, by running php -m in a shell and checking if it is listed.
+Permission denied after configuring filesystem permissions: make sure your system /tmp directory is also writable. If you are on a shared host without access to /tmp, configure Drupal to use a temporary directory inside your sites/default/files path via Administration → Configuration → Media → File system. There is a discussion about this issue on Drupal.org that is helpful.