Skip to content
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

First pass edits to README. #4

Closed
wants to merge 2 commits into from
Closed

First pass edits to README. #4

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b89b3b1
First pass edits to README.
rosiel Jul 4, 2023
429f1a6
Update readme.
Jul 18, 2023
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
55 changes: 30 additions & 25 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,29 +31,29 @@ installation from this template.
## Forking Warning

This is not intended to be an upstream fork that your institution will be
pulling changes from. Instead this repository acts as a template, where the
intention is to make a new Git repository from it. By copying the contents of
this repository into your institution's Git repository. For which your
institution will then be responsible for.

This is for a few reasons. Namely, we can't guarantee forward compatibility with
the changes made by your institution to a fork of this Git repository. Your
institution must be responsible for it's own configuration, as changes to
pulling changes from. Instead this repository acts as a template. The
intention is to make a new Git repository from it by copying the contents of
this repository into your institution's Git repository, for which your
institution will then be responsible.

This is for a few reasons. Primarily, we can't guarantee forward compatibility
with the changes made by your institution to a fork of this Git repository.
Your institution must be responsible for it's own configuration, as changes to
configuration **cannot** easily be shared across Drupal sites.

## Assumptions

This template assumes you'll be using `docker compose` for running your site in
production on a **single server**. If that is not your intention you may want to ask
in the community slack about existing examples for your chosen infrastructure.
This template assumes you'll be running your site in Docker
on a **single server**. If that is not your intention you may want to ask
in the Islandora Slack about existing examples for your chosen infrastructure.

This template assumes a single site installation and isn't configured for a
This template is set up for a single site installation and isn't configured for a
[Drupal multisite](https://www.drupal.org/docs/multisite-drupal). It is possible
to add the functionality for that later, but it is left to the implementer to do
those additional changes.

While Islandora can be setup to use a wide variety of databases, tools and
configurations this template is limited to the following.
configurations this template is set up for the following.

- `blazegraph` is included by default.
- `crayfish` services are included by default.
Expand All @@ -66,21 +66,20 @@ configurations this template is limited to the following.

> N.B. Although alternate components and configurations are supported by
> Islandora, for simplicities sake the most common use-case is shown. For
> example `mariadb` is used rather than `postgresql` is provided by this
> repository.
> example `mariadb` is used rather than `postgresql`.

See the [customizations](#customizations) steps afterwards about removing unwanted features.

# Requirements

- [Docker 20.10+](https://docs.docker.com/get-docker/)
- [Docker 20.10+](https://docs.docker.com/get-docker/) **This is the Docker Engine version, not Docker Desktop**.
- [Docker Compose](https://docs.docker.com/compose/install/linux/) **Already included in OSX with Docker**
- [mkcert 1.4+](https://github.com/FiloSottile/mkcert)

# Automatic Setup

After installing the [requirements](#requirements), run the following command
for an automated setup, it is roughly equivalent to the
for an automated setup. It is roughly equivalent to the
[Manual Setup](#manual-setup).

```bash
Expand All @@ -91,7 +90,8 @@ You should now have a folder with the `SITE_NAME` you provided to the above
script with the basics completed for you.

On your platform of choice [GitHub], [GitLab], etc. Create a new Git repository
for your new site.
for your new site. (Not necessary for a development instance unless you want to
save changes to it.)
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this accurate? I feel quite silly going through all this "institution" stuff to spin up a temporary dev sandbox.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I guess, rather, is it "recommended" that a git repo and remote be created for development projects? What changes might get saved here?


In the following sections the [GitHub], [GitLab], etc; organization will be
referred to as `INSTITUTION`, and the Git repository will be referred to as
Expand Down Expand Up @@ -157,7 +157,7 @@ git push

Just as this repository is not intended to be an upstream fork, neither is the
[islandora-starter-site]. It is a starting point from which your institution
will customize and manage your Islandora installation.
will customize and manage Drupal for your Islandora installation.

1. Unpack the [islandora-starter-site] using the latest release, or the `main`
branch (from the root of your repository).
Expand Down Expand Up @@ -205,34 +205,34 @@ The previous sections will have set you up with a Git repository to start from,
but more customization is likely needed.

Read through each following sections and follow the steps if you deem them
applicable to your institutions situation.
applicable to your institution's situation.

## Set environment properties

Edit [.env] and replace the following line, with a name derived from your site
Edit [.env] and replace the following line with a name derived from your site
name:

```bash
COMPOSE_PROJECT_NAME=isle-site-template
```

After setting up a remote Docker image registry like [DockerHub]. Set the
following line to your use your image registry:
If setting up your own images on a remote Docker image registry like [DockerHub],
set the following line to your use your image registry:

```bash
# The Docker image repository, to push/pull custom images from.
# islandora.io redirects to localhost.
REPOSITORY=islandora.io
```

After purchasing a domain name for your production site, set the following line
If using a purchased a domain name for your production site, set the following line
to your new domain:

```bash
# The domain at which your production site is hosted.
DOMAIN=islandora.dev
```
Lastly update the default email to that of your sites administrator:
Lastly update the default email to that of your site's administrator:

```bash
# The email to use for admin users and Lets Encrypt.
Expand Down Expand Up @@ -272,6 +272,11 @@ git commit -am "Replaced README.md from provided template."
```bash
git push
```
# Usage

Instructions for the rest of the Islandora setup are in
[README.template.md](./README.template.md), which after following the previous step
is at README.md.

[.env]: .env
[DockerHub]: https://hub.docker.com/
Expand Down
63 changes: 33 additions & 30 deletions README.template.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -59,39 +59,42 @@ There are a number of `docker-compose.yml` files provided by this repository:

## Override

This repository ignores `docker-compose.override.yml` which will be included in
any `docker compose` commands you invoke by default.
This git repository does not track `docker-compose.override.yml` which will
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

why? Are we supposed to put secret stuff there?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is intended to be the location where you drop your institution's specific overrides.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, but I just created a Git Repo to hold all my institution's customizations (so I thought). What was the purpose of doing that, if they're not to be included?

be included by default in all `docker compose` commands you invoke.

Two platform dependent templates that allow for access to the hosts `SSH agent`
are provided for `development` environments.

Simply copy the appropriate `docker-compose.PLATFORM.yml` file into
Simply copy the appropriate* `docker-compose.PLATFORM.yml` file into
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Which one is appropriate? If I'm running Mac or Windows, do I choose darwin or linux?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Darwin is Mac and linux for Linux but there doesn't seem to be an example for windows.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Indeed. I don't think most new Mac users know they're on "Darwin" so I'll add a comment to that effect.

`docker-compose.override.yml`, on your development machine.

Any additional changes that are for your local / development environment can
then be added to `docker-compose.override.yml`.
then be added to `docker-compose.override.yml`. Because they're not tracked...
rosiel marked this conversation as resolved.
Show resolved Hide resolved

## Building

You can build your locally using `docker compose`
You can build your development environment locally using `docker compose`
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What does "build" mean since there are so many steps after this?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I take it that "build" actually means "run the build steps defined in docker-compose.yml" which only exists for the Drupal service. It does this by pulling/getting the image specified then presumably doing stuff to it, but I can't see what that entails.


```bash
docker compose --profile dev build
```
This has the effect of...
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(put here as a placeholder, that this section should at some level explain what building is since you haven't even pulled images yet, I can't imagine what's being built.)


## Pulling
## Pulling Docker Images

The `docker compose` file provided require that you first pull the islandora
The `docker compose` file provided requires that you first pull the islandora
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"first" implies... before building (previous step)? Before the next step? If that's the case why not just state this as the next step?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Before anything can happen within a container you must download that image to build the container with. It sounds like this is the intent.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It is implied that this requirement is a quirk of our particular docker-compose.yml file.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's also after the 'build' step which confuses me.

images with the following command:

```bash
docker compose --profile dev --profile prod pull --ignore-buildable --ignore-pull-failures
```

Both `dev` and `prod` are included so that...
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also, confused by this.


## Running / Stoping / Destroying

You must specify a profile either `dev` or `prod` to use `docker compose` files
provided by this repository.
You must specify a profile - either `dev` or `prod` - to use the `docker compose` files
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

docker compose is the name of the command, docker-compose[-foo].yml is the name of the files. I feel weird referring to the files by the command, but if that's common practice I'll let it be.

provided by this repository. Running/stopping/destroying for each profile is outlined below.

### Development Profile

Expand All @@ -101,9 +104,9 @@ Use the `dev` profile when bring up your local/development environment:
docker compose --profile dev up -d
```

You must wait several minutes for the islandora site to install. When completed
you can see the following in the output from the `drupal-dev` container, with
the following command:
After all containers are "Started", you must wait several minutes for the Islandora
site to install. When completed, you can see the following in the output from the
`drupal-dev` container, with the following command:

```bash
docker compose logs -f drupal-dev
Expand All @@ -115,16 +118,16 @@ docker compose logs -f drupal-dev
#####################
```

For all accounts in the development profile the username and password is set to
For all accounts in the development profile the username and password are set to
the following:

| Credentials | Value |
| :---------- | :------- |
| Username | admin |
| Password | password |

If you have the domain in your `.env` set to `islandora.dev` you can access all
the services at the following URLs.
If you have the domain in your `.env` set to `islandora.dev` (default), you can
access all the services at the following URLs.

| Service | URL |
| :--------- | :---------------------------------------- |
Expand Down Expand Up @@ -173,7 +176,7 @@ To **destroy all data** from your production environment:
docker compose --profile prod down -v
```

## Pushing
## Pushing Docker Images

Pushing requires setting up either a [Local Registry](#local-registry), or a
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What is pushing docker images? When would you want to do it?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Docker's cli pushes images to the repository.

Pushing a forked Docker image to your own repository can serve several purposes:

  • Version Control: By forking and pushing a Docker image to your own repository, you create a version-controlled copy of the image. This allows you to track changes and modifications you make to the image separately from the original repository. It gives you control over the image's evolution and allows you to maintain your own customized version.
  • Customization: Forking a Docker image provides an opportunity to customize it according to your specific needs. You can modify the image's configuration, add or remove packages, include additional dependencies, or make any other changes required by your application. Pushing the modified image to your own repository ensures that you have a stable, consistent version of the image that reflects your customizations.
  • Security and Compliance: Forking and pushing a Docker image to your own repository allows you to apply security updates and patches independently from the original image. You can regularly update and scan the image for vulnerabilities, ensuring that it meets your organization's security and compliance requirements. This way, you have control over the security of the image and can address any potential issues promptly.
  • Dependency Control: If you rely on a specific version of a Docker image in your development or production environment, forking and pushing it to your own repository ensures that you have a reliable source for that particular version. It prevents potential issues arising from changes or updates made to the original image, as you have a dedicated repository where you control the availability and versioning of the image.
  • Offline Access: Having a forked Docker image in your own repository allows you to have a local copy that you can access even when the original image repository is not available. This can be useful in scenarios where you have limited or unreliable internet connectivity, or when the original repository is unavailable due to maintenance or downtime.

Overall, pushing a forked Docker image to your own repository gives you control, flexibility, and the ability to customize and manage the image according to your specific requirements. It ensures that you have a stable and version-controlled source for the image, independent of the original repository. Welcome to use any or all of this if you'd like.

[Remote Registry](#remote-registry). Though you may want to use both concurrently.
Expand Down Expand Up @@ -355,7 +358,11 @@ mkcert \

## Upgrading Isle Docker Images
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is ambiguous and could mean:

  • upgrading from ISLE to site template
  • packaging updates that you've made to ISLE docker images
    It also seems implied that you could be using non-ISLE docker images, and that seems not to be spelled out here.


Edit [.env] and replace the following line, with your new targeted version:
First, read the **release notes** for the versions between your current version
and your target version, as manual steps beyond what is listed here will likely
be required.

Edit [.env] and replace the following line with the desired new version tag:

```bash
# The version of the isle-buildkit images to use.
Expand All @@ -364,18 +371,14 @@ ISLANDORA_TAG=x.x.x

Then you can [pull](#pulling) the latest images as described previously.

Then read the **release notes** for the versions between your current version
and your target version, as manual steps beyond what is listed here will likely
be required.

Of course **make backups** before deploying to production and test thoroughly.

## Drupal Development

For local development via the [development profile], an [IDE] is provided which
can also support the use of [PHPStorm].
can also support (how?) the use of [PHPStorm].
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What does it mean for a built-in IDE to "support" phpstorm? Where are the instructions to make the built-in IDE work with phpstorm? Or is it the bind-mounted codebase-ish directories which support the use of phpstorm?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I "think" it supports the use of phpstrom.


There are a number of bind mounted directories so changes made in the following
There are a number of bind mounted directories and changes made in the following
files & folders will persist in this Git repository.

- /var/www/drupal/assets
Expand All @@ -386,8 +389,8 @@ files & folders will persist in this Git repository.
- /var/www/drupal/web/themes/custom

Other changes such as to the `vendor` folder or installed modules are **not**
persisted, to disk. This is by design as these changes should be managed via
`composer` and baked into the Drupal Docker image.
persisted in Git. This is by design as these changes should be managed via
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure if you meant for real that changes are not persisted to disk. Based on what little i know of Docker, it's possible that changes are ephemeral and live in the container, not on a volume, so your statement would be accurate. But I don't think that's what your'e going for.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it's a safe assumption that any manual changes to the vendor/ directory is a bad idea and should be looked at as volatile because running a composer command will wipe out those changes or could be dropped by a build process.

`composer` and baked into the Drupal Docker image for production.

Changes made to `composer.json` and `composer.lock` will require you to rebuild
the Drupal Docker image, see [building](#building) for how.
Expand All @@ -400,13 +403,13 @@ the Drupal Docker image, see [building](#building) for how.
# Production

Running in production makes use of the [production profile], which requires
either manually provided secrets, or generating secrets. As well as a properly
configured DNS records as is described in the following sections.
either manually provided secrets, or generating secrets. It also requires a
properly configured DNS record as described in the following sections.

## Generate secrets

To be able to run the production profile of the [docker-compose.yml] file the
referenced secrets and JWT public/private key pair must be created. There is
referenced secrets and JWT public/private key pair must be created. There are
inline instructions for generating each secret in [docker-compose.yml].

Alternatively you can use the [generate-secrets.sh] `bash` script to generate
Expand All @@ -417,7 +420,7 @@ them all quickly.

## Production Domain

The [.env] has a variable `DOMAIN` which should be set to the production sites
The [.env] has a variable `DOMAIN` which should be set to the production site's
domain.

```bash
Expand Down Expand Up @@ -499,4 +502,4 @@ sudo chcon -R -t container_file_t secrets/*
[lets-encrypt]: https://letsencrypt.org/
[mkcert]: https://github.com/FiloSottile/mkcert
[PHPStorm]: https://github.com/Islandora-Devops/isle-buildkit#phpstorm
[production profile]: #production-profile
[production profile]: #production-profile