Skip to content

Update readme #208

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
CGillen wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Update readme #208

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
125 changes: 80 additions & 45 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,32 @@
# Oregon State University Libraries Drupal

This is based on the main OSU Drupal Distribution.
This is the Drupal site for the [main library website](https://library.oregonstate.edu), based on the main OSU Drupal Distribution.

## Update workflow

To update drupal or any of the modules, choose a method below:

Note: Make sure to get the latest code before attempting either of these `git pull`

### Automated (Recommended)

Requirements:

1. Github [Personal Access Token](https://github.com/settings/tokens) for composer to access custom repositories.
1. Composer auth tokens in default install location: `~/.composer/auth.json`. Otherwise update `docker-compose.yml`

Process:

1. Run `dev/update.sh`
1. You will be given several update options:
- Dry-run: run `compose update -o --dry-run` to see which modules have updates
- Dev: run `compose update -o --dev` to install updates for the development environment
- Prod: run `compose update -o --no-dev` to install updates for the production environment
1. Your `composer.lock` file will update according to your `composer.json` file and selection
1. Then you can commit the changed `composer.json` and `composer.lock` and push

### Manual

1. Get the latest code `git pull`
1. Enter the container `docker compose exec apache bash`
1. Check for Drupal library & modules updates `composer outdated drupal/\*`
1. If you want to only check for packages that have minor version updates
Expand All @@ -23,24 +43,6 @@ This is based on the main OSU Drupal Distribution.
- `composer update`
1. Commit the changed composer.json and composer.lock and push

### Automated

Requirements:

1. Local `composer` install
1. Github [Personal Access Token](https://github.com/settings/tokens) for composer to access custom repositories.
1. Composer auth tokens in default install location: `~/.composer/auth.json`. Otherwise update `docker-compose.yml`

Process:

1. Run `dev/update.sh`
1. You will several update options:
- Dry-run: run `compose update -o --dry-run` to see which modules that needs updates
- Dev: run `compose update -o --dev` to install updates for the development environment
- Prod: run `compose update -o --no-dev` to install updates for the production environment
1. Your `composer.lock` file will update according to your `composer.json` file and selection
1. Then you can commit the changed `composer.json` and `composer.lock` and push

## Local Development

### Build the container locally:
Expand All @@ -52,53 +54,49 @@ Process:
#### Advanced:

- For the development version of the container:
- `docker build --target=development --tag=osuwams/drupal:9-apache-dev .`
- `docker build --target=development --tag=<tag> .`
- For the Production version
- `docker build --target=production --tag=osuwams/drupal:9-apache .`

### Start the containers:

- `docker compose up -d`
- `docker build --target=production --tag=<tag> .`

### View the logs:
### Useful docker commands:

- `docker compose logs -f apache`

### Stop the containers:

- `docker compose down`

### Stop the containers and remove any database config and solr data:

- `docker compose down -v`
- Start the containers in detached mode (you retain access to the terminal)
- `docker compose up -d`
- Open a terminal in the Apache container
- `docker compose exec apache bash`
- View the Apache/PHP logs
- `docker compose logs -f apache`
- Stop the containers
- `docker compose down`
- Stop the containers and remove any database config and solr data:
- `docker compose down -v`

### Setup for theme or module development

- Copy `docker-compose.override.example.yml` to `docker-compose.override.yml`
- Replace `volumes` definitions with overrides in the format of: `/path/to/local/folder:/path/to/container/folder`. The first definition has the correct path to the theme already set.
- Replace `volumes` definitions with overrides in the format of: `/path/to/local/folder:/path/to/container/folder`. The first definition has the correct path to the container theme folder already set.
- Remove any other example definitions

## Environment Variables

### The Main variable for the Drupal Site.
### The Main variables for the Drupal Site.

- DRUPAL_DBNAME
- The Database Name to use
- The Database Name to use to setup the drupal and mariadb containers.
- DRUPAL_DBUSER
- The Database User with permissions to that Database.
- DRUPAL_DBPASS
- The Password to the Database User.
- DRUPAL_DBHOST
- The Host name that the Database Server is running on

#### Optional Parameters

- DRUPAL_DBHOST
- The Host name that the Database Server is running on
- Default: localhost
- DRUPAL_DBPORT
- The Port the Database Server is running on
- Default: 3306
- PRIVATE_FILE_PATH
- The absolute file path to where private files are stored. This should NOT be in webroot
- The absolute file path to where private files are stored in the **_container_**. This should NOT be in webroot
- Default: '' (undefined & unused in drupal)

### Memcache Variables
Expand Down Expand Up @@ -126,12 +124,49 @@ Process:
- The Port the Database Server is running on
- Default: 3306

## Importing the production database
## Importing the production database (OSU Library Developers only)

- Rename the existing default database (`dev/mariadb-init/default.sql`) such that it's not a sql file (`default.sql.tmp`)
- Delete or rename the existing default database (`dev/mariadb-init/default.sql`) such that it's not a sql file (`default.sql.tmp`)
- Run the `dev/db-pull.sh` script to dump and pull the live database into `dev/mariadb-init/live_dump.sql`
- Delete the existing `mariadb` database: `docker compose down -v` (This will also delete the Solr index)
- Stop and start all containers
- Wait for `mariadb` to finish importing the database (`docker compose logs -f mariadb`)
- Visit local site and confirm import
- You will be missing all public & private files from production. This can later be fixed with a new scipt or the `stage_file_proxy` module

## Beavernetes (Kubernetes) deployment information:

OSULP uses a `kubernetes` backed deployment infrastructure we delightfully named `beavernetes`

### Deployed Images

- Apache/PHP - Built - Based on ghcr.io/osu-wams/php:8.2-apache which is eventually based on the official php:8.2-apache
- wodby/mariadb:10.11-3.28.3 - Database. It can be almost any database backend
- solr:8-slim - Powers search
- memcached:1.6-alpine - Will cache site when we can untangle it

### Required Environment Variables

- TEMP_FILE_PATH - Full path to temporary file folder in apache/php pod
- PRIVATE_FILE_PATH - Same, but for private files. This should be OUTSIDE of webroot
- LIBCAL_LOCATIONS - (for some reason) A single element array with a hash of {<libcal_location_id>: <location_name_lowercase>}
- LIBCAL_CLIENT_SECRET - Secret key for connecting to Libcal
- LIBCAL_CLIENT_ID - Our Libcal client ID
- DRUPAL_MEMCACHEHOST - Memcached host
- DRUPAL_MEMCACHE - true/false enable memcache
- DRUPAL_HASH_SALT - A salt value (Large "a-Z0-9" string)
- DRUPAL_DBHOST - Host name for database
- DRUPAL_DBPORT - Port for db host
- DRUPAL_DBUSER - User for db host
- DRUPAL_DBPASS - Pass for db host
- DRUPAL_DBNAME - Name of database
- DB_DRIVER - Type of driver to db

### Important Mounts

All of these would be in the apache/php deployment

- <PRIVATE_FILE_PATH> from env vars
- `/var/www/html/docroot/sites/default/files` The default path to servable public files
- `/etc/apache2/apache2.conf` path to apache config
- `/usr/local/etc/php/php.ini` path to php config
4 changes: 2 additions & 2 deletions docker-compose.override.example.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,6 @@ services:
environment:
DRUPAL_STAGING_SITE: https://www.example.com
volumes:
- /local/path/to/theme:/var/www/html/docroot/themes/custom/osulp-drupal-subtheme
- /local/path/to/module:/var/www/html/docroot/modules/custom/a-module
- /local/path/to/theme:/var/www/html/docroot/themes/custom/osulp-drupal-subtheme-dev
- /local/path/to/module:/var/www/html/docroot/modules/custom/a-module-dev
- /any/other/local/files:/that/you/need/for/development