Improvements on docker-build script

[bjones1]

This is a separate issue to follow up on the previous discussion.

The problem

Even after significant improvements in the docs and the code, the Docker installation process is long and challenging:

• It's the entry point for any developer interested in contributing to the project, so making this work well is important to attracting others to contribute to the project.
• It's 10 steps long, increasing the probability of failure for people trying to follow it.
• It contains OS-specific choices, making the instructions harder to follow.
• It contains instructions for two cases (production vs deployment), making the instructions harder to follow.
• It lacks checks to make sure the previous steps succeeded.
• It fails in a lot of unique ways for each user; there doesn't seems to be an obvious, consistent problem to fix.

Challenges

• The script is currently written in Python, but Python isn't installed by default on OS X or Windows, requiring manual installation steps before any automation can occur.
• There's a lot of OS-dependent code before we get to Docker, which is difficult.
• I don't have a Mac to test on, so there's a fair amount of guessing on anything OS X related.

Successes

Working with developers to walk through the install process and looking at and fixing problems they've encountered has improved the situation a lot already. We're in a much better place now.

Goals

Develop a process which:

• Requires the download and execution of only one file (script/binary/whatever).
• Can gather information from the user (Github userid, build a production vs development server, books to install, etc.), then perform the installation process without additional user input.
• Has some diagnostic ability to determine if each step succeeded before proceeding to the next step.
• Retains the existing docker-tools script, rather than subsuming it, so that the docker-tools functionality remains available for advanced users.
• Is written in a language which runs on Windows/Linux/Mac, instead of requiring a separate script for each platform.
• Provide both a GUI and command-line operation, again to make scripting/advanced use easier.
• Develop a good test suite using a virtual machine, so it's easy to try the process out.

[bjones1]

I would appreciate any comments/thoughts/ideas from people who have been through this process -- @barbarer, @davidfarmer, @bnmnetp, @pearcej ...

[bnmnetp]

I think we should separate development and production completely. For production we would ideally have a docker image in a public docker registry so that one can simply download it. This is essentially what I do on Runestone Academy, but I'm using a private registry for our containers. Doing a public version of this would ensure that

Perhaps instead of thinking that everyone should install Runestone in development mode we ought to think of solutions for different use cases? What are those use cases? Here are a few to get started.

1. Someone who wants to contribute to Runestone and help with coding. OK, this person is a developer or is in training to be a developer, and they are going to have to be comfortable installing some things, working with git, and navigating the command line. For a user like this perhaps we should be looking at something like a Homebrew installation. There is a Homebrew for macOS, Linux and WSL - brew install runestonedev
2. An author who just wants to build books? - can just install runestone or pretextbook to get started. The CLI team even has a nice setup for you in the cloud.
3. An Author who wants to test their book in a full Runestone Server environment -- I am working on an interface that would allow an author to pull their book to runestone academy, build it, and preview it.
4. An author who wants more locally but does not need the whole instructor interface should be able to install runestone/pretextbook plus our bookserver using SQLLITE as the DB.
5. A developer who just wants to help out with the Runestone Components

Maybe our work / time is better spent finding really clean solutions to a set of the common use cases rather than trying to simplify the whole giant environment?

[bjones1]

I like the idea of supporting use cases. I think we have good support for authors, with more to come -- support for running books on the Runestone Server env you run will be great! Likewise, providing cloud-based authoring (me + CLI) will also be nice.

For the production use case, I agree that a prebuilt container makes sense. But, there's still a lot that needs to be done to get to this point: install the Docker Desktop, Python 3 (unless we can somehow move docker-tools and rsmanage into the container), WSL/Ubuntu (Windows), docker-tools and rsmanage, install books, add users, choose passwords, set the e-mail address for password resets, etc. This IMHO still needs some scripting/intelligence to support well.

• On OS X, I like the idea of creating a Homebrew formula to manage most of the install process. This seems like a very nice way to go. This means OS X users will need to install Homebrew themselves, which is a reasonable expectation for most Mac people.
• On Ubuntu, a copy-and-paste command would work; it would download a Python script then run that. (I don't like creating a new apt package, since users have to install a key first, which is more hassle).
• On Windows, a copy-and-paste command should work; it would install Python, then download and run a Python script. But, there's still a lot of work needed to take out many of the manual steps in the current process.

If we can accomplish this, then the developer use case becomes even simpler, since getting a useful production system takes care of almost everything needed for developers.

[bjones1]

I think we should provide a GUI for some of the currently CLI-based tasks after the server is running -- a nice webpage running on the BookServer that allows an instructor to select and install books, create base courses, add students, etc.

[bnmnetp]

We have a web interface for all of that already don't we? The instructor pages...

[bjones1]

Select and install books: I don't know how to do this in the instructor interface.

Create base courses: I don't know how to do this in the instructor interface.

Manage students: the admin / manage students tab in the instructor interface does this already -- you're right. I will update Docker instructions to point them to this page, since I think that's a bit easier than rsmanage for our audience (teachers wanting to run their own server, but not necessarily experienced with CLI).

[bnmnetp]

I thought you meant creating a course from existing books.

Maybe this server I am working on can serve the role you are asking for. - clone book, create base course, build/deploy

Teachers that want to run their own server but with little command line experience.... The care and feeding of a complicated system requires some skills. I would not stop anyone from making it easier to install and use, but given all of the goals and tasks I have for Runestone that are on my plate I don't think I would choose to prioritize that one.

I think we get much more bang for our effort getting to the point where we make it easier to get more people contributing to Runestone.

[bjones1]

True -- this will definitely take some work. I'll keep this as a lower priority. Having your server-side improvements (clone book, create base course, etc.) would certainly make it easier for a significant group of users.

[bjones1]

Some notes on ideas/blockers:

Blocker: how to determine if the Docker Desktop is installed in Windows? The discussion on Poweruser on WMIC didn't work for me.

TODO: Create a Windows batch file that checks for WSL and Ubuntu and installs them if not, then starts this script in Ubuntu. Perhaps https://github.com/kaisalmen/wsltooling?

[github-actions[bot]]

Stale issue message