Feature gh#91 development environment setup with docker (#99)

* Fixed sourcemap property - _config_dev.yml

When trying to run the command `jekyll serve` using `_config_dev.yml`,
it failed with the following error:
  Conversion error: Jekyll::Converters::Scss encountered an error while
  converting 'assets/css/atom.scss': undefined method `to_sym' for true:TrueClass Did
you mean? to_s
------------------------------------------------
Jekyll 4.0.0   Please append `--trace` to the `serve` command
               for any additional information or backtrace.
------------------------------------------------
This happens because in `_config_dev.yml` sourcemap is set to `true`,
while the documentation at
https://github.com/jekyll/jekyll-sass-converter stated the allowed
values are `never`, `always` and `development`.

* Docker based development environment

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

It is an implementation for
InnerSourceCommons/innersourcecommons.org#91

With this development, with the command `docker-compose up`, a docker
image is built and a docker contain is run serving the webpage, that
can be accessed on https://localhost:4000

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

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)
- 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.

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 on Docker for Mac and Docker Toolbox

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

* Docker support enhancement

Added future proof support to Docker for windows
with setting `JEKYLL_ENV` to a value different than
`development`.
With this setting, the ip used in `--host` is not
going to override site.url.
The alternative would be use `build --watch` + a separate
web server for static files, but I did not see any advantage,
and also I wanted to have the livereload option of `serve`.

Added comments on the Dockerfile to explain some
of the non-intuitive parts.

Added support for livereload.

Added EXPOSE statements to the Dockerfile to document ports in use.

References:
- 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

* Docker Toolbox enablement

This commit enables the usage of Docker Toolbox with the command
`docker-compose -f docker-compose-toolbox.yml up`.

A similar result could be achieved by editing `_config_dev.yml`
to have 'url':'' and tweak the Dockerfile command to include
the --force_polling option, but I did not want to change the
`_config_dev.yml` without being sure of the consequences for
non docker users.

* Page edit tests documentation

I added a section in CONTRIBUTING.md on how to test the page
edits locally, with and without docker.

So far the instructions only covered testing the build locally,
but not how to serve the page while editing.

Co-authored-by: Guilherme Dellagustin <[email protected]>

.dockerignore

@@ -0,0 +1,2 @@
+!Gemfile
+!Gemfile.locks

CONTRIBUTING.md

@@ -18,6 +18,29 @@ Contributions to this repo are welcome. Please follow the following guidelines:
 * The navigational links at the top of the pages are at \_data/\_navigation.yml
 * Event pages are under *events*; other main pages are under *pages*
 
+### Testing edits locally
+
+In both of options described below the website will be served with _livereload_, which means your changes should be automatically reflected on the browser after you save them.  
+Unless stated otherwise, the website will be served at https://localhost:4000.
+
+#### Native development environment
+
+Install ruby and the project dependencies, then run the command:
+```
+jekyll serve --config _config.yml,_config_dev.yml --livereload
+```
+
+#### Docker development environment
+
+If you have docker installed in your machine, you can run the development environment with the following commands on the root of the repository:
+- `docker-compose up` - for Docker on linux or [Docker Desktop](https://www.docker.com/products/docker-desktop) (Windows or Mac)
+
+OR
+- `docker-compose -f docker-compose-toolbox.yml` - for [Docker Toolbox](https://docs.docker.com/toolbox/toolbox_install_windows/) (legacy solution for older Mac and Windows systems)
+  - The website will be available at `https://<docker machine ip>:4000`, which is typically https://192.168.99.100:4000 - you can discover the ip with the command `docker-machine ip`
+
+In both cases a Docker image will be build on the first time you run the commands, this step can take a few minutes.
+
 ## git command line tips
 
 * Do this once when you've checked out your fork of the main ISC repo: `git remote add upstream https://github.com/InnerSourceCommons/innersourcecommons.org.git`

Dockerfile

@@ -0,0 +1,25 @@
+FROM ruby:2.7.0-alpine3.11
+
+WORKDIR /InnerSource
+ADD Gemfile .
+ADD Gemfile.lock .
+
+# Required in order to build gem native extenstions
+# see https://github.com/docker-library/ruby/issues/163
+RUN apk add --no-cache g++ gcc make musl-dev
+
+# Required to build in Docker for Mac, otherwise it will raise the
+# error: Could not find 'bundler'
+RUN bundle update --bundler
+
+RUN bundle install
+
+# Required so that Jekyll will not override site.url with the host passed by --host
+ENV JEKYLL_ENV=docker
+
+EXPOSE 35729
+EXPOSE 4000
+
+# On --host 0.0.0.0
+# It is required so that Jekyll will accept connections outside of localhost and 127.0.0.1
+CMD jekyll serve --host 0.0.0.0 --livereload --config /source/_config.yml,/source/_config_dev.yml -s /source

README.md

@@ -4,6 +4,6 @@ This repo primarily serves to host the pages for InnerSource Commons. The master
 
 ## Contributing
 
-Please see [our contribution guidelines](CONTRIBUTING.md)
+Please see [our contribution guidelines and instructions](CONTRIBUTING.md).
 
 

_config_dev_toolbox.yml

@@ -0,0 +1,8 @@
+# This file is needed for setting up the development environment
+# with docker toolbox.
+# It reverts the absolute paths configured in _config_dev.yml
+# Without this, assets and links build with site.url would fail to
+# load or open.
+
+url: ''
+urlimg: 'images/'

docker-compose-toolbox.yml

@@ -0,0 +1,13 @@
+version: "3.7"
+services:
+  jekyll:
+    build: .
+    image: innersource-website-devenv
+    ports:
+    - "4000:4000" # webpage
+    - "35729:35729" # live reload
+    volumes:
+    - ./:/source
+    # --force_polling is necessary as the sharing of the filesystem from host to the toolbox vm does not seem to trigger the regular rebuild on changes
+    # _config_dev_toolbox.yml - see the comments on the file
+    command: jekyll serve --host 0.0.0.0 --force_polling --livereload --config /source/_config.yml,/source/_config_dev.yml,/source/_config_dev_toolbox.yml -s /source

docker-compose.yml

@@ -0,0 +1,10 @@
+version: "3.7"
+services:
+  jekyll:
+    build: .
+    image: innersource-website-devenv
+    ports:
+    - "4000:4000" # webpage
+    - "35729:35729" # live reload
+    volumes:
+    - ./:/source