YMCA Website Setup/Upgrade Documentation (Based on Bash History)

This document outlines the steps taken to set up and potentially upgrade a YMCA website instance using the Open Y Drupal distribution (ycloudyusa/yusaopeny-project) and the DDEV local development environment. The process involves creating project instances, managing databases, installing dependencies, and updating the Drupal site.

Phase 1: Initial Project Setup (CLEAN_WS_9)

This phase focuses on creating the initial project environment named CLEAN_WS_9.

Create Project Scaffold:
- composer create-project ycloudyusa/yusaopeny-project:2.7 CLEAN_WS_9 --no-install
- Creates the project directory structure and composer.json file for version 2.7 without installing dependencies immediately.
Navigate to Project:
- cd CLEAN_WS_9/
- Changes the current directory to the newly created project folder.
Configure DDEV:
- ddev config
- Initializes DDEV configuration for the project, prompting for project name, docroot, and project type (drupal9).
Start DDEV Environment:
- ddev start
- Starts the Docker containers (web server, database, etc.) defined by the DDEV configuration.
Install Dependencies:
- ddev composer install
- Installs all PHP dependencies defined in composer.json within the DDEV container.
Import Initial Database:
- cp ../MY_PROJECT/docroot/10april.sql docroot/
- Copies an existing database dump (10april.sql) from a presumed previous project (MY_PROJECT) into the docroot of CLEAN_WS_9.
- ddev drush sql-cli < docroot/10april.sql (Inferred from ddev drush sql-cli command - user likely piped the file in)
- Imports the SQL dump into the DDEV database.
Configure Database Prefix (Alexandria YMCA Specific):
- Navigate to docroot/sites/default.
- Open the file settings.ddev.php in a text editor.
- Add the following line within the PHP tags, typically near other database settings:
```
$databases['default']['default']['prefix'] = 'openy_alex';
```
- This step configures a specific database table prefix, necessary for the Alexandria YMCA instance.
Initial Drupal Updates & Cache Clear:
- ddev drush cr
- Clears Drupal's caches.
- ddev drush updatedb
- This step is needed for getting information about potentially non existing modules. Use CTRL-C to exit from command.
Install Additional Module:
- ddev composer require 'drupal/jquery_ui_accordion:^2.1'
- Adds the jquery_ui_accordion module (version 2.1 or compatible) as a project dependency using Composer.
- ddev drush updatedb
- Runs database updates again, potentially including updates required by the newly added module. (Note: drush en jquery_ui_accordion might have been needed here if not enabled automatically or by configuration).

Phase 2: Creating a Baseline Backup

A database snapshot is created from the CLEAN_WS_9 environment after the initial setup and module addition.

Create Database Dump:
- ddev drush sql-dump | gzip -9 > latest_d9_openy.sql.gz
- Exports the current state of the CLEAN_WS_9 database using Drush, compresses it using gzip, and saves it to latest_d9_openy.sql.gz.
- mv latest_d9_openy.sql.gz ../
- Moves the backup file to the parent directory.

Phase 3: Setting Up a Second Environment (CLEAN_WS_10)

This phase involves creating a new, separate project environment, potentially for testing an upgrade or a cleaner build using the latest Open Y version.

Create New Project Scaffold:
- cd ..
- composer create-project ycloudyusa/yusaopeny-project CLEAN_WS_10 --no-install
- Creates a new project scaffold named CLEAN_WS_10 using the latest available version of ycloudyusa/yusaopeny-project (no version constraint specified).
Navigate and Configure DDEV:
- cd CLEAN_WS_10/
- ddev config
- ddev start
- Navigates into the new project, configures DDEV, and starts the environment.
Install Dependencies:
- ddev composer install
- Installs dependencies for the CLEAN_WS_10 project.
Prepare Database Import:
- cp ../latest_d9_openy.sql.gz docroot/
- Copies the database backup created from CLEAN_WS_9 into the docroot of CLEAN_WS_10.
- cd docroot/
- gunzip latest_d9_openy.sql.gz
- Navigates into the docroot and unzips the database backup.
Import Database:
- ddev drush sql-cli < latest_d9_openy.sql (Inferred)
- Imports the database dump from CLEAN_WS_9 into the CLEAN_WS_10 environment.
Configure Database Prefix (Alexandria YMCA Specific):
- Repeat step 7 from Phase 1 for the CLEAN_WS_10 environment if using the same database prefix.
- Navigate to docroot/sites/default.
- Open the file settings.ddev.php in a text editor.
- Add the following line within the PHP tags, typically near other database settings:
```
$databases['default']['default']['prefix'] = 'openy_alex';
```
Apply Updates:
- ddev drush cr
- ddev drush updatedb
- Clears cache and applies any necessary database updates. This is crucial after importing a database into a potentially newer codebase.

Phase 4: Troubleshooting and Cleanup (CLEAN_WS_9)

It appears some cleanup or troubleshooting was performed on the original CLEAN_WS_9 instance.

Module Investigation/Removal:
- cd ../../CLEAN_WS_9
- find ./ | grep 'entity_reference'
- Navigates back to CLEAN_WS_9 and searches for files related to entity_reference. This module is part of Drupal core but might have been causing issues or was intended for removal if replaced by another mechanism.
- ddev drush pmu entity_reference
- Attempts to uninstall the entity_reference module. (Note: This is a core module and uninstalling it directly is unusual and potentially problematic unless specific steps are taken).
- ddev drush pmu jquery_ui_accordion
- Uninstalls the jquery_ui_accordion module previously added.

Phase 5: Final Transfer and Verification (CLEAN_WS_10)

The cleaned state of CLEAN_WS_9 is transferred to CLEAN_WS_10.

Create Final Backup from CLEAN_WS_9:
- ddev drush sql-dump | gzip -9 > latest_d9_openy.sql.gz
- mv latest_d9_openy.sql.gz ../
- Creates a new, compressed database dump from the modified CLEAN_WS_9.
Restore to CLEAN_WS_10:
- cd ../CLEAN_WS_10
- cp ../latest_d9_openy.sql.gz docroot/
- cd docroot/
- gunzip latest_d9_openy.sql.gz
- ddev drush sql-cli < latest_d9_openy.sql (Inferred)
- Navigates to CLEAN_WS_10, copies the new backup, unzips it, and imports it, overwriting the previous database state.
Configure Database Prefix (if needed):
- Ensure the database prefix setting added in Phase 3, Step 6 is still present and correct in docroot/sites/default/settings.ddev.php after importing the database.
Final Updates and Checks:
- ddev drush cr;
- ddev drush updatedb
- Clears cache and runs database updates on CLEAN_WS_10 after the final import.
- ddev drush status
- Checks the status of the Drupal installation (version, database connection, etc.).
- ddev describe
- Displays information about the DDEV environment (URLs, database credentials).
- ddev drush uli
- Generates a one-time login link for accessing the site as an administrator.
- Fix Missing Site Logo:
  - After logging in using the uli link, navigate to the theme settings page, typically /admin/appearance/settings/openy_carnation (adjust theme name if different).
  - Locate the "Logo image" setting.
  - If the logo is missing or incorrect, update the path to the correct location within the theme, e.g., themes/contrib/openy_carnation/dist/img/logo-white.png.
  - Save the configuration.

Conclusion

This process involved setting up an initial Open Y environment (CLEAN_WS_9), configuring a database prefix, adding modules, creating a backup, setting up a second environment (CLEAN_WS_10 potentially with a newer Open Y version), restoring the backup and reapplying the prefix, performing cleanup/troubleshooting on the original environment, and finally transferring the cleaned state to the second environment for final testing and verification, including a check for the site logo. The use of two separate environments suggests a careful approach, possibly for testing an upgrade path or resolving issues found in the initial setup before finalizing the target environment.

podarok/upgrade.md