How to fork and use isle dc for your institution - Islandora-Devops/isle-dc GitHub Wiki

This is what this repo does and how to fork it and modify it with little to no merge conflicts from the community.

TL;DR

It downloads the Drupal codebase repo from a source setup for Islandora if the codebase/ directory doesn't exist.
It builds the containers and installs the modules from the composer.lock file.
You need to fork this repo and add your own custom.Makefile for customizations.
Don't edit the original Makefile
Run the command to generate your own codebase after you initially build isle (see below)
Replace the existing codebase with the one generated after you shut down isle-dc
Add all modules, themes, libraries, etc. to the composer.json
Do not use Drush to download and install

What does this repo do when it builds?

Before you start, look at the list of make commands (run make help from within this repo's directory). This gives you a list of all the make commands you intend to use from the command line. There are more than this, but those functions are intentionally not given a help description because they might be destructive if run by themselves.

The .env file in the root of the directory will need to be modified to match your domain and other settings. You don't need to edit this to get isle-dc to build locally for you. You can leave the defaults and check the documentation for more information on this.

It uses the codebase/ directory as the Drupal root directory for a site. It builds all of the microservice needed and containers to run Islandora. Once the Drupal container is started it looks within the codebase directory and runs the 'composer install' to install all of the support modules, libraries, themes, etc. Here's a list of directories and what they are for.

codebase/web/libraries/ for Drupal libraries
codebase/web/modules/contrib/ for Drupal modules
codebase/web/profiles/contrib/ for Drupal profiles
codebase/web/themes/contrib/ for Drupal themes
drush/Commands/contrib/ for Drupal drush commands
codebase/web/modules/custom/ for Drupal custom-module
codebase/web/profiles/custom/ for Drupal custom-profile
codebase/web/themes/custom/ for Drupal custom-theme

Warning::: Installing a module without using composer to do so will cause issues. Any time composer is to run composer update or install, it will likely remove any undeclared modules/themes/libraries/etc.

To generate your own codebase

Start isle-dc
Run this command to generate a new codebase directory. docker-compose exec -T drupal with-contenv bash -lc 'composer create-project --no-interaction -- islandora/islandora-starter-site new_codebase dev-feature/track-original-version'
Rename the newly created directory "new_codebase to whatever you want.
Add a .gitignore file to the new_codebase directory. You do not want modules and libraries bloating your repo. Here's an example
Create a git repo and push the contents of the new_codebase directory to the repo.
Create a blank custom.Makefile file if you haven't already. There is no header needed. This will be injected at the top of the original Makefile.
Copy the starter_dev function from the Makefile into the custom.Makefile
Rename the starter_dev function and help text.
Change the Github repo to point to the newly created repo

.PHONY: jhu_up
## JHU: Build the JHU site.
jhu_up: QUOTED_CURDIR = "$(CURDIR)"
jhu_up: generate-secrets
	$(MAKE) starter-init ENVIRONMENT=starter_dev
	if [ -z "$$(ls -A $(QUOTED_CURDIR)/codebase)" ]; then \
		docker container run --rm -v $(CURDIR)/codebase:/home/root $(REPOSITORY)/nginx:$(TAG) with-contenv bash -lc 'git clone -b main https://github.com/jhu/digital-collections /home/root;'; \
	fi
	$(MAKE) set-files-owner SRC=$(CURDIR)/codebase ENVIRONMENT=starter_dev
	docker-compose up -d --remove-orphans
	docker-compose exec -T drupal with-contenv bash -lc 'composer install'
	$(MAKE) starter-finalize ENVIRONMENT=starter_dev

In this example, the starter_dev function in the Makefile was copied to the custom.Makefile. It was renamed to jhu_up, the help text was modified to make it clear it's specific to our institution, and the Github repo was modified to point to the newly created codebase.

Now run `make clean to remove everything. If the codebase is still there, delete it.
Run your new make command. For this example make jhu_up.

Example: custom.Makefile This file is under active development and is specific to JHU's needs. This is for educational use, not something to copy into your custom.Makefile. You can if you want to, but it's not intended for that.