Document how to start and stop ISLE instances

[ysuarez]

Issue description

I was trying out installing ISLE local on two new machines and realized I was not 100% sure which docker command(s) to use, for example docker-compose down versus 'docker down' if I wanted to preserve data.

Same goes for information of how to start it up again if ISLE was already installed successfully.

I want to volunteer to help write this, but I need to make sure I use the correct commands.

My understanding so far is I should use:

docker-compose down for preserving data

docker-compose down -v for removing volumes, but preserving containers.

and

docker system prune --all to remove all containers.

Finally, I should use docker-compose up -d to bring up a ISLE system that was previously installed.

For locations for where to put something like the above

• Near the end of demo, local, staging, prod installation instructions
• Inside cookbook section
• ???

Thoughts?

[noahwsmith]

Maybe you're asking for a cleanup of https://github.com/Islandora-Collaboration-Group/ISLE/blob/master/docs/cookbook-recipes/isle-cheatsheet-docker-commands.md ?

[noahwsmith]

cc @dwk2 @marksandford

[ysuarez]

@noahwsmith mostly no since my focus for this particular issue is to add some optional steps (shut down that preserves data, start up post install) to the demo/local/staging/prod, and to create a cook book entry for for these same steps . Though I am fine with only providing a cook book entry for shut down that preserves data and start up post install, without making changes to the demo/local/staging/prod install docs since these are not officially install steps.

Looking over the Docker cheatsheet yesterday (and others days) it was not 100% clear which one of all those commands was the one to use for simple shutdown start up out of all the options. For example, last week I chose docker down since I was not sure. Though I did know not to use docker-compose down -v, because in a few places in the docs (and cheat sheet) it is clear the volumes are removed. With that being said I find the Docker cheat sheet very useful. It helped me start understanding docker better.

For the record, I am used to seeing documentation for setting up software that at the end of the installation section the often tell you how to shut down the "instance" of whatever you just installed. This would be especially helpful for the "demo" instructions (since folks may want to shut it down quickly more often), and maybe not as much for the local/staging/prod. Though I still think it would be nice to offer these steps, for example, as an optional last step (# 12) in the "local" instructions after "Step 11: Check-In the Newly Created Islandora Drupal Site Code Into is Git Repository" or even just place a link to the cookbook and/or the Docker cheat sheet after step # 11.

Finally, I am also interested in putting in another issues to remove some "cookbook" like content in the Docker cheat sheet and move it over to the cook book section, just to separate the style of content now that there is a dedicated cookbook section. (This is just a suggestion.).

Thoughts/comments?

[noahwsmith]

Ok, so it's rather that you believe the use of these commands should be woven into the current tutorial docs. That seems very reasonable. I'll defer to @marksandford and @dwk2 on strategy for doing that...

[ysuarez]

BTW, I can create a pull request or write out some sample content in this issue just to push this further to save work and to help visualize how the change may look since it could not look good in the end.

[dwk2]

Hi @ysuarez, I think you are making some good points here about organization and availability of Docker commands in the install/update workflow documentation.
I like your suggestion to write out some sample content here to have a better idea of what you are proposing. In general, the constraints that we deal with when changing documentation is that we have multiple scenarios to update: demo, local, staging, prod; and for "local, staging, prod" we have separate docs for a "new install" and a "migration".
Two final thoughts:

• Maybe we should provide a link to the ISLE Cheat Sheet: Docker Commands at the top of each document for: demo, local, staging, and prod.
• Maybe an improvement to the ISLE Cheat Sheet: Docker Commands would be to make a new section at top of page of the most frequent commands used to pull images, docker up, and docker down? And then under that, we could have a horizontal separator followed by the summary of many docker commands?

Thanks @ysuarez for bringing up the need for more clarity here!

[marksandford]

I just want to chime in with a little bit of caution. Because of the potential disaster that "down -v" can cause, we've intentionally left that out of some docs. I would prefer that we only reference that particular command in docs related specifically to development processes. Most users won't need to use it at all, and (in my opinion) it's frighteningly easy to do a lot of damage without docker asking if you're sure. That being said, I'm all for more clarity. Mark

…

_______________________________________ Mark Sandford Systems Librarian Assistant Professor in the LibrariesColgate University Libraries 315*228-7363 [image: Colgate University email wordmark]

On Thu, Dec 19, 2019 at 11:52 AM David Keiser-Clark < ***@***.***> wrote: Hi @ysuarez <https://github.com/ysuarez>, I think you are making some good points here about organization and availability of Docker commands in the install/update workflow documentation. I like your suggestion to write out some sample content here to have a better idea of what you are proposing. In general, the constraints that we deal with when changing documentation is that we have multiple scenarios to update: demo, local, staging, prod; and for "local, staging, prod" we have separate docs for a "new install" and a "migration". Two final thoughts: - Maybe we should provide a link to the ISLE Cheat Sheet: Docker Commands <https://islandora-collaboration-group.github.io/ISLE/cookbook-recipes/isle-cheatsheet-docker-commands/> at the top of each document for: demo, local, staging, and prod. - Maybe an improvement to the ISLE Cheat Sheet: Docker Commands <https://islandora-collaboration-group.github.io/ISLE/cookbook-recipes/isle-cheatsheet-docker-commands/> would be to make a new section at top of page of the most frequent commands used to pull images, docker up, and docker down? And then under that, we could have a horizontal separator followed by the summary of many docker commands? Thanks @ysuarez <https://github.com/ysuarez> for bringing up the need for more clarity here! — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#358?email_source=notifications&email_token=AEKTOH3633S63L3DBFQHESDQZORE3A5CNFSM4J4SPB2KYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEHKHHJA#issuecomment-567571364>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AEKTOH6BRBIFDRXBDA5V7HTQZORE3ANCNFSM4J4SPB2A> .

[dwk2]

Yes, thank you @marksandford . @ysuarez , we've intentionally included that command only 1 time in all of our docs, and that is at the bottom of the docker commands list and is flagged with a big caution statement. :)

[ysuarez]

@dwk2 I agree that since we would need to edit so many install docs for my first suggestion that it may be better to just put a link to the cheat sheet/cookbook in each one.

I also really like this suggestion form you...

"Maybe an improvement to the ISLE Cheat Sheet: Docker Commands would be to make a new section at top of page of the most frequent commands used to pull images, docker up, and docker down? And then under that, we could have a horizontal separator followed by the summary of many docker commands?"

@marksandford I totally agree (now that I have more experience) that "down -v" is for development / advanced testing. Just realized there are no warnings when used! I have used it so much because of my earlier install issues. BTW, the warnings in the cheat file are great for the "dangerous" commands.

BTW, "down -v" is also mentioned in the README in the context of cleaning up after testing. Maybe we can consider adding the (safe) start and stop in the README too, but not necessarily or again just put in a link to cookbook cheat sheet (if not already there).

[dwk2]

@ysuarez Please feel free to put in this PR. (Just make sure to first follow the directions to run this Cleanup Script for the 1.4.0 release to reduce the size of your ISLE repo.)

[dwk2]

Hi @ysuarez , do you still want to add the following contribution, or does it no longer seem necessary?

"Maybe an improvement to the ISLE Cheat Sheet: Docker Commands would be to make a new section at top of page of the most frequent commands used to pull images, docker up, and docker down? And then under that, we could have a horizontal separator followed by the summary of many docker commands?"

[g7morris]

Hi @ysuarez

Is this something you are still working on? If so, perhaps we could get your upcoming PR ready for the 1.5.6 release at the end of April?

Thanks,
Gavin

[ysuarez]

@g7morris Give me a couple of days this week to revisit this issue. At this point I have a much greater understanding of ISLE and Docker, though still not an expert. Let me see if I think I can come up with something worthwhile in a PR.

[ysuarez]

I just tried to add a pull request to add a new link in the install pages' footer section that points to the "ISLE Cheat Sheet" that does cover how to stop containers.

Though I am wanting to write some content in the "ISLE Cheat Sheet" to choose to use docker-compose stop versus docker-compose down in ISLE. Not clear is one is always preferred. I do understand that if I am about to upgrade the ISLE when a new version comes out that I need to choose docker-compose down to then run docker-compose pull, for example.

[g7morris]

docker-compose down is the "preferred" one as it deletes containers and networks each time. docker-compose stop keeps containers and their state which sometimes is wanted. I prefer down because I always want a new changed state of the container upon each restart. HOWEVER docker-compose down -v is a dreaded command as that will zap / destroy Docker volumes in addition to containers and networks, that is bad unless your intention is to wipe out your site as one might if doing local development and starting from scratch.

Yes when upgrading, down makes more sense as you will be changing the underlying software with a docker image swap out.

Hope this helps.

[ysuarez]

@g7morris Thanks for the clarification. I would suggest that the community considers my PR, the addition of the link in the footer section to the "ISLE Cheat Sheet: Docker Commands" page, as a good way to take care of the main concerns from this issue.

Though I would be interested in creating a new issue later on to work on adding the general advice the you gave about there being a preference for usingdocker-compose down versus docker-compose stop for typical ISLE workflows. As well as explaining how the users data is not affected unless the "-v" is used, for example. I would consider an addition to the Docker cheat sheet page to cross link the existing ISLE docs page on how data is stored locally to assure folks that the local data wil be safe (unless "prune" or "-v" is used).

Finally I am hoping I can re-use/re-purpose the "ISLE Cheat Sheet: Docker Commands" page for ISLE(8) docs in the near future.

[g7morris]

@marksandford & @dmer Can I elect one or both of you to review please? Otherwise I'm fine with including @ysuarez 's work in the upcoming ISLE 1.5.6 release and attributing his contribution in the release notes. ;) Thanks again Yamil