https://github.com/web-illinois/illinois_framework_project
Instructions for setting up an Illinois Drupal Framework distribution on web.illinois.edu cPanel hosting.
https://github.com/web-illinois/illinois_framework_project
composer-project drupal illinois-framework
Last synced: 25 days ago
JSON representation
Instructions for setting up an Illinois Drupal Framework distribution on web.illinois.edu cPanel hosting.
- Host: GitHub
- URL: https://github.com/web-illinois/illinois_framework_project
- Owner: web-illinois
- Created: 2020-05-21T15:15:55.000Z (almost 6 years ago)
- Default Branch: 1.x
- Last Pushed: 2025-10-07T16:39:04.000Z (6 months ago)
- Last Synced: 2025-10-07T18:53:25.696Z (6 months ago)
- Topics: composer-project, drupal, illinois-framework
- Language: PHP
- Homepage: https://webtheme.illinois.edu/about/drupal/
- Size: 73.2 KB
- Stars: 6
- Watchers: 5
- Forks: 1
- Open Issues: 10
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Illinois Framework Project
This is a [Composer](https://getcomposer.org/)-based installer for the [Illinois Drupal Framework distribution](https://github.com/web-illinois/illinois_framework_profile). It is intended to be used on the University of Illinois cPanel instance at https://web.illinois.edu. For information about what content types and modules are included, please check out the [Illinois Drupal Framework distribution repository](https://github.com/web-illinois/illinois_framework_profile). This distribution is maintained by the [Illinois WIGG-Drupal group](https://webtheme.illinois.edu/about/drupal/). An example site that showcases the features of this distribution can be found at [https://drupal.webtheme.illinois.edu/](https://drupal.webtheme.illinois.edu/).
## Prerequisites
* A fresh cPanel account on https://web.illinois.edu
* [Composer](https://getcomposer.org/) installed in your cPanel environment ([instructions below](#installing-composer-in-your-cpanel-environment))
* Github [personal access token](https://docs.github.com/en/github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token) that is [enabled for SSO](https://docs.github.com/en/github/authenticating-to-github/authenticating-with-saml-single-sign-on/authorizing-a-personal-access-token-for-use-with-saml-single-sign-on)
* Save the token string somewhere safe. You will need it for each new site you install.
* You will be prompted for it after you run the composer command below that installs your site. Paste it into the terminal window and hit enter. You will not see it when pasting.
* Creating individual keys for each install is advisable but will require more maintenance and record keeping. If you will be sharing your cPanel account with others you should create a new key.
* The key you enter will be stored and reused when you run the update script.
## Installing Composer in your cPanel environment
Starting in September 2025, `composer` is no longer included by default with cPanel. Installation and updates of Drupal sites should be performed using the [Composer dependency manager](https://getcomposer.org). Composer is a tool for dependency management in PHP.
To install composer in your cPanel environment, run the script below from your home directory:
```sh
#!/bin/bash
# Download the installer
php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
# Ensure the destination directory exists
mkdir -p ${HOME}/bin
# Run the installer
php composer-setup.php --install-dir=${HOME}/bin --filename=composer
# Remove the installer
php -r "unlink('composer-setup.php');"
echo "✅ Composer installed successfully! Reload your shell environment to start using composer."
```
After running the script, reload your shell environment and verify composer is installed by running `composer --version`. You should occasionally update your version of composer by running `composer self-update`.
## Creating a Illinois Drupal Framework site in web.illinois.edu
1. From the cPanel dashboard, open up Terminal (or SSH into your site if you prefer)
2. Run the `composer` command below from your home (~) directory. The script will pause when you are prompted for your GitHub token. _Be sure to take note of the admin password displayed at the end of the script._ Expect this install to take about 10 minutes.
```
composer create-project --remove-vcs --no-dev --repository="{\"url\": \"https://github.com/web-illinois/illinois_framework_project.git\", \"type\": \"vcs\"}" web-illinois/illinois_framework_project:1.x-dev illinois_framework
```
3. Access the site at _\_.web.illinois.edu
4. Login to your site at _\_.web.illinois.edu/user/login
Congrats! You should now have a Illinois Drupal Framework site!
## After installation
After your site is installed, it is recommended that you perform these extra steps:
* In the "Update Manager Settings" (`/admin/reports/updates/settings`) set the e-mail address to a mailbox you monitor.
* Change the admin password to something more secure and store it in a password manager
* Go through the site setup at https://drupal.webtheme.illinois.edu/site-setup
## Extra information:
* Be sure to add the `drush` alias to your .bashrc file using the [instructions below](#drush-and-drupal-console)
* The files for your site are stored in the ~/illinois_framework directory
* Files uploaded to the site are stored in ~/illinois_framework/docroot/sites/default/files
* The MySQL database username and password is stored in ~/.my.cnf
* If you lose/forget your Drupal admin password, you can reset it with drush using the command `drush upwd admin "NEWPASSWORD"`
## Shibboleth authentication
Instructions for adding Shibboleth to your Illinois Drupal Framework site is [in the wiki](https://github.com/web-illinois/illinois_framework_project/wiki/Setting-up-Shibboleth-authentication-within-your-Illinois-Framework-Drupal-site).
## Updating your site
Security updates are regularly relased for Drupal and its modules, so it's vital to keep your site updated. To update your site, open the terminal for your site, `cd` to the directory `~/illinois_framework`, and run the following commands:
```bash
composer update --with-all-dependencies --no-dev -o
drush updb -y; drush cr; drush ccr; drush config-distro-update -y
```
The above commands assume you have a `drush` alias set up already. See below for adding the alias to your site.
### Upgrading to version 4.0 of the framework (Released February 2024)
Version 4 of the framework was released 2/7/2024. Instructions on how to upgrade your site can be found [in the wiki](https://github.com/web-illinois/illinois_framework_project/wiki/Upgrading-your-site-to-version-4.0-from-3.2).
### Upgrading to version 3.0 of the framework
Version 3 of the framework was released 3/7/2023. Instructions on how to upgrade your site can be found [in the wiki](https://github.com/web-illinois/illinois_framework_project/wiki/Upgrading-your-site-to-version-3.0-from-2.4).
## Backing up your site
It's important to periodically back up your site. The most important part of a Drupal site is the database. The below commands will create a `~/backups` folder and create a database backup of your site. It will also create a backup of your composer.json and composer.lock, which can be useful in restoring a site's code back to a previous state. Replace the *YOUR_DB_NAME* with the name of your database.
```bash
mkdir -p ~/backups
mysqldump YOUR_DB_NAME | gzip > ~/backups/db.$(date +%F.%H%M%S).sql.gz
tar cvf - ~/illinois_framework/composer* | gzip > ~/backups/composer.$(date +%F.%H%M%S).tar.gz
```
## Drush
[Drush](https://www.drush.org/) is installed and available for your Framework site at `~/illinois_framework/vendor/bin/drush`.
You can add the below alias command to your `~/.bashrc` to keep from having to type the whole path each time:
```bash
alias drush='$HOME/illinois_framework/vendor/bin/drush'
```
## Extending the Illinois Drupal Framework
If you would like to extend the Illinois Drupal Framework with additional [modules](https://www.drupal.org/project/project_module) or [themes](https://www.drupal.org/project/project_theme), you need to use composer to add them to your site.
| Task | Composer |
|-------------------------------------------------|---------------------------------------------------|
| Installing a contrib project (latest version) | ```composer require drupal/PROJECT``` |
| Installing a contrib project (specific version) | ```composer require drupal/PROJECT:1.0.0-beta3``` |
| Updating a single contrib project | ```composer update drupal/PROJECT``` |
## Source Control
You should commit the files in the `~/illinois_framework` directory to source control. You can run `git init` in the `~/illnois_framework` directory to initialize the directory as a git repository. After that, you'll want to commit the files and push them to a remote repository.
If you peek at the ```.gitignore```, you'll see that certain directories, including all directories containing contributed projects, are excluded from source control. In a Composer-based project like this one, **you SHOULD NOT commit your installed dependencies to source control**.
When you set up the project, Composer will create a file called ```composer.lock```, which is a list of which dependencies were installed, and in which versions. **Commit ```composer.lock``` to source control!** Then, when your colleagues want to spin up their own copies of the project, all they'll have to do is run ```composer install```, which will install the correct versions of everything in ```composer.lock```.
## How do I update Drupal core?
It's counterintuitive, but **don't add `drupal/core` to your project's composer.json!** The Illinois Drupal Framework manages Drupal core for you, so adding a direct dependency on Drupal core is likely to cause problems for you in the future.
## Developing the Illinois Drupal Framework
Instructions on setting up a local Docker-based development environment are located at [https://github.com/web-illinois/illinois_framework_localdev](https://github.com/web-illinois/illinois_framework_localdev).