Feature gh#91 development environment setup with docker

[dellagustin]

This commit enables the usage of Docker for setting up a development environment.

It is an implementation for

91

With this development, with the command docker-compose up or docker-compose -f docker-compose-toolbox.yml up (for Docker Toolbox), a docker image is built and a docker contain is run serving the webpage, that can be accessed on http://localhost:4000 (or http://<docker machine ip>:4000 for Docker Toolbox)

Files:

• .dockerignore - ensures that only the necessary files are used in the context passed to the docker image build, saving build time
• Dockerfile - The commands used to build a docker image
• docker-compose.yml - Configuration for docker-compose, that enables a simple development environment setup, automating the image build and container orchestration
• docker-compose-toolbox.yml - docker-compose file with tweaks for Docker Toolbox (see comments on files)
• _docker_dev_toolbox.yml - overrides url configuration for Docker Toolbox (see comments on file)

Known limitations:

• ~Website is not rebuilt automatically when a file is changed, requiring a container restart (this was expected to work out of the box with jekyll serve, but testing showed it did not work)~
  • It was already working for Docker for Mac, implemented for Docker Toolbox with using the command line option --force_polling
• ~Docker Toolbox is not supported - with this version of docker, the page can be loaded, but assets are not loaded, as the browser tries to fetch them from http://0.0.0.0, and the website must be accessed on the IP returned by docker-machine ip. More investigation is necessary.~
  • Implemented support with d538dc20f1905185e0e4adb68ee8258f57c417c0

Explanations:

• RUN apk add --no-cache g++ gcc make musl-dev - necessary for building gem native extensions (eventmachine) - Error message "You have to install development tools first."
• RUN bundle update --bundler - Image build on Docker Toolbox worked without this, but when trying to build the image on Docker for Mac, it raised the following error: find_spec_for_exe': Could not find 'bundler' (1.16.1) required by your /InnerSource/Gemfile.lock. (Gem::GemNotFoundException) To update to the latest version installed on your system, run `bundle update --bundler`.
• --host 0.0.0.0 - without this line, jekyll will only accept traffice incoming from localhost or 127.0.0.1, which is not the case when using Docker for Mac or Docker Toolbox, as it forwards traffic from the host to the container. Without this line, the browser will show errors ERR_CONNECTION_REFUSED (Toolbox) or ERR_EMPTY_RESPONSE (Mac).

Remarks:

• Only tested (by the author) on Docker for Mac and Docker Toolbox

Letf overs and follow ups:

• [x] Documentation on how to use the Docker environment is missing
  • Added with 88e41f2fc25cb9d50c00dc6f1cd6cc6b600f05c2
• [ ] Documentation on the overall solution for Docker environment is missing
  • The number of references, development iterations (until ready) and questions during review shows that even though the final solution is concise, there is a lot of non trivial aspects to it, therefore I would like to include some kind of documentation that explains how it works and more details on the whys of some things (decisions), and unused alternatives, this should help future refactoring - even though there is extensive information on the github issue #91 and this pr (#99) I have the strong feeling git repos should be self contained regarding their documentation (i.e. portable to other git managers such as bitbucket or gitlab)
• Decision Needed: Implement the left overs in this PR or approve and Merge the PR as is and document the leftovers with follow up issues - DONE - Document how to use in this PR, document overall Docker environment solution in a separate PR.
• [ ] Create follow up issue to review Contributing instructions with respect to test the build locally (see https://github.com/InnerSourceCommons/innersourcecommons.org/pull/99#issuecomment-595498798)
• [ ] Create follow up issue to reduce the technical debt introduce with this PR
  • Separate docker-compose files for regular docker and toolbox
  • Unexplained need for RUN bundle update --bundler only on Docker Desktop, but not on toolbox
  • Not using jekyll/jekyll image

References:

• https://hub.docker.com/_/ruby
• https://docs.docker.com/engine/reference/builder/#dockerignore-file
• https://docs.docker.com/engine/reference/builder/
• docker-library/ruby#163 (How to install eventmachine)
• https://stackoverflow.com/questions/41485217/mount-current-directory-as-a-volume-in-docker-on-windows-10
• https://stackoverflow.com/questions/42893475/how-to-run-jekyll-serve-pointing-to-another-directory
• https://stackoverflow.com/questions/50540721/docker-toolbox-error-response-from-daemon-invalid-mode-root-docker
• https://medium.com/@Charles_Stover/fixing-volumes-in-docker-toolbox-4ad5ace0e572
• https://sashabrava.github.io/2018/making-Jekyll-available-on-local-network.html
• microsoft/vscode-remote-release#764
• https://stackoverflow.com/questions/16608466/connect-to-a-locally-built-jekyll-server-using-mobile-devices-in-the-lan/16608698
• https://jekyllrb.com/docs/configuration/options/#serve-command-options
• https://tonyho.net/jekyll-docker-windows-and-0-0-0-0/
• Cannot set site.url to a different address than the --host flag address in development
  • jekyll/jekyll#5743
• https://docs.docker.com/engine/reference/builder/#expose

PS: I carried https://github.com/InnerSourceCommons/innersourcecommons.org/commit/f4edc9fd7c92006eaeba8c3cafe9758f8f58e4fe to this PR by mistake, but I imagine #98 will be approved before this one, so I will not undo that.

[maxcapraro]

Thanks a lot for contributing this work, @dellagustin! 🙏

I think I might not be able to review it within the next 24h - but anyway: I am really looking forward to playing around with your implementation and will happily provide review feedback asap :)

[dellagustin]

Hi @maxcapraro Did you have the chance to review this PR? If you need any help with the setup, please let me know.

[maxcapraro]

Thanks for your patience with this one :) I'll look into it today

[dellagustin]

Hi @maxcapraro , thanks for the review 👍 I answered your comments, there are some decisions to be made (solve now or accept and track technical debt). Can you take a look? The docu I can write and push a new commit.

[maxcapraro]

Thanks for the clarifications, @dellagustin! So far: looks good to me (except for the one comment re: documentation). Let's add that and then (if Jo and Cedrid haven't raised an opinion re: the two alternative docker files by then) let's merge :)

[dellagustin]

Hi @maxcapraro , I added documentation. I created a new section for testing the page edits locally. I think the build part is a bit confusing (i.e. general flow vs steps for ubuntu, no mention of the htmlproofer step), and as it is, I am not sure it adds much value, if the contributor is already using jekyll serve, but I did not want to change this for now.

[maxcapraro]

It's beautiful. Thank you @dellagustin!