First pass edits to README. #4
Conversation
| @@ -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.) | |||
There was a problem hiding this comment.
Is this accurate? I feel quite silly going through all this "institution" stuff to spin up a temporary dev sandbox.
There was a problem hiding this comment.
I guess, rather, is it "recommended" that a git repo and remote be created for development projects? What changes might get saved here?
| @@ -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 | |||
There was a problem hiding this comment.
why? Are we supposed to put secret stuff there?
There was a problem hiding this comment.
This is intended to be the location where you drop your institution's specific overrides.
There was a problem hiding this comment.
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?
|
|
||
| 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 |
There was a problem hiding this comment.
Which one is appropriate? If I'm running Mac or Windows, do I choose darwin or linux?
There was a problem hiding this comment.
Darwin is Mac and linux for Linux but there doesn't seem to be an example for windows.
There was a problem hiding this comment.
Indeed. I don't think most new Mac users know they're on "Darwin" so I'll add a comment to that effect.
|
|
||
| ## Building | ||
|
|
||
| You can build your locally using `docker compose` | ||
| You can build your development environment locally using `docker compose` |
There was a problem hiding this comment.
What does "build" mean since there are so many steps after this?
There was a problem hiding this comment.
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.
|
|
||
| The `docker compose` file provided require that you first pull the islandora | ||
| The `docker compose` file provided requires that you first pull the islandora |
There was a problem hiding this comment.
"first" implies... before building (previous step)? Before the next step? If that's the case why not just state this as the next step?
There was a problem hiding this comment.
Before anything can happen within a container you must download that image to build the container with. It sounds like this is the intent.
There was a problem hiding this comment.
It is implied that this requirement is a quirk of our particular docker-compose.yml file.
There was a problem hiding this comment.
It's also after the 'build' step which confuses me.
| @@ -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 | |||
There was a problem hiding this comment.
What is pushing docker images? When would you want to do it?
There was a problem hiding this comment.
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.
| @@ -355,7 +358,11 @@ mkcert \ | |||
|
|
|||
| ## Upgrading Isle Docker Images | |||
There was a problem hiding this comment.
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.
| 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]. |
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
I "think" it supports the use of phpstrom.
| @@ -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 | |||
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
|
|
||
| ```bash | ||
| docker compose --profile dev build | ||
| ``` | ||
| This has the effect of... |
There was a problem hiding this comment.
(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.)
| 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... |
There was a problem hiding this comment.
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 |
There was a problem hiding this comment.
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.
|
Closing, too complicated to be addressed. |
Trying to clear up some unclear grammar and sentences in the README.md and README.template.md files.