PECE System Administration

How do I install PECE?

PECE is a Free Software-based Drupal distribution, therefore the 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 a supported Nginx version; see the official Drupal system requirements page below for current Nginx version constraints.

• 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 developed on GitHub. You can obtain the most recent version by visiting the project's repository:

https://github.com/PECE-project/drupal-pece

To install PECE using Composer (recommended), run:

composer create-project pece/pece-distro YOUR_PROJECT_NAME

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 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 — required for outbound HTTP requests.

• php-ssh2 — optional; needed for SFTP-based backup destinations.

• 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 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:

composer create-project pece/pece-distro YOUR_PROJECT_NAME
cd YOUR_PROJECT_NAME

2. Create an empty database:

mysql -u $YOUR_USER -p -e "CREATE DATABASE $YOUR_DB_NAME CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"

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

Important: Replace CHANGEME with a strong, unique password before running this command. Never use a weak or default password on a publicly accessible site.

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 775
• web/sites/default/files/private (private files) — permissions 750 or 770

I want to use HTTPS with PECE. How can I do that?

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). Configure Apache or Nginx to use .../YOUR_PROJECT_NAME/web as the document root (not the project root), so that files such as vendor/ and composer.json are not exposed. 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.

How do I update the site information?

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.

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 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.

How do I configure SMTP so that emails can be sent from the platform?

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. 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 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 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 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.

• 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: 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.

• 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.