Add development environment instructions (closes #19)

[jwflory]

This pull request adds new documentation to explain how to create a development environment to build and preview the fossrit.github.io website locally.

I tagged a few people for review because I'd like feedback to improve these instructions. By following the below instructions, you should be able to run a local development instance of the fossrit.github.io website. It should only take executing a script. If you have Docker already installed, it should "Just Work™".

Could anyone actually try this and let me know if it works easily for them? Is anything confusing or could it be better explained?

[Nolski]

Looks good to me! Personally I'd advocate using docker-compose instead of a self written shell script for this case though

[Tjzabel]

Looks good! 👍

Since I have a relatively fresh install of Fedora 29, I didn't have docker yet. I can verify the contributing instructions work from downloading docker to running the script and viewing the development site on http://localhost:4000.

[thenaterhood]

All good :). I figured that could be the case but I took the opportunity to mention it just in case it was something you didn't know.

…

On Sun, Dec 2, 2018, 12:59 Justin W. Flory ***@***.***> wrote: ***@***.**** commented on this pull request. ------------------------------ In .github/CONTRIBUTING.md <#35 (comment)> : > +Install Docker: + +* Linux + * [Fedora](https://developer.fedoraproject.org/tools/docker/docker-installation.html) + * [Ubuntu](https://docs.docker.com/install/linux/docker-ce/ubuntu/) +* [macOS](https://docs.docker.com/docker-for-mac/install/) +* [Windows](https://docs.docker.com/docker-for-windows/install/) + +### Run development script + +In a new window, run the [`start_devel_env.sh`](https://github.com/FOSSRIT/fossrit.github.io/blob/master/start_devel_env.sh) script. +This script downloads a Jekyll Docker container and builds the website. +Once it starts, you can access a local version of the website by visiting this URL: + +``` +http://localhost:4000 In this case, I did it this way because I'm lazy and like to double-click on a line and copy+paste it to my browser bar. 😅 It was a conscious personal preference. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#35 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/ACdwxItVLPYoGitfN4SzIOaOGTzP0jRrks5u1BTlgaJpZM4Y9LyJ> .

[jrtechs]

I really like the docker deployment and how it automatically regenerates the source. We should definitely add this to the RITlug jekyll site.

I think we should also include the instructions for deploying this normally through Ruby since it allows us to run RSpec and it is slightly faster on older hardware.

[ghost]

On Mon, Dec 03, 2018 at 04:55:04AM -0800, Jeffery Russell wrote: [...]

I think we should also include the instructions for deploying this normally through Ruby since it allows us to run RSpec and it is slightly faster on older hardware.

I'd be happy to see that and might be in a better place to use that and give feedback than the docker install. I ran into some snags downloading a 168MB component of the upstream docker image yesterday. I had to walk away from it yesterday to do other things, and so let it try to complete in the meantime. I haven't gotten back to it to see if it completed.

[jwflory]

@jrtechs:
I really like the docker deployment and how it automatically regenerates the source. We should definitely add this to the RITlug jekyll site.

Thanks. I can work on upstreaming it when I get Travis CI support for testing the website with the Docker container.

@jrtechs:
I think we should also include the instructions for deploying this normally through Ruby since it allows us to run RSpec and it is slightly faster on older hardware.

@ritjoe:
I'd be happy to see that and might be in a better place to use that and give feedback than the docker install.

This makes sense. I am uncertain if I can do this in a timely manner though because I do not want to install the dependencies on bare metal. Is this something either of you would be interested in contributing?

[jrtechs]

@jwflory I'd love to document how to run it without docker. I'll probably get around to it tomorrow afternoon.

[ghost]

On Sat, Dec 01, 2018 at 05:23:21PM -0800, Justin W. Flory wrote: @jwflory requested your review on: #35 Add development environment instructions (closes #19).

The error at the bottom goes away when I ```mkdir _site``` ~/fossrit.github.io$ . start_devel_env.sh Fetching gem metadata from https://rubygems.org/........... Fetching concurrent-ruby 1.1.3 Installing concurrent-ruby 1.1.3 Fetching i18n 0.9.5 Installing i18n 0.9.5 Fetching minitest 5.11.3 Installing minitest 5.11.3 Fetching thread_safe 0.3.6 Installing thread_safe 0.3.6 Fetching tzinfo 1.2.5 Installing tzinfo 1.2.5 Fetching activesupport 4.2.10 Installing activesupport 4.2.10 Fetching public_suffix 2.0.5 Installing public_suffix 2.0.5 Fetching addressable 2.5.2 Installing addressable 2.5.2 Fetching io-like 0.3.0 Installing io-like 0.3.0 Fetching archive-zip 0.11.0 Installing archive-zip 0.11.0 Using bundler 1.17.1 Fetching mini_mime 1.0.1 Installing mini_mime 1.0.1 Fetching mini_portile2 2.3.0 Installing mini_portile2 2.3.0 Fetching nokogiri 1.8.5 Installing nokogiri 1.8.5 with native extensions Fetching rack 1.6.11 Installing rack 1.6.11 Fetching rack-test 1.1.0 Installing rack-test 1.1.0 Fetching regexp_parser 1.3.0 Installing regexp_parser 1.3.0 Fetching xpath 3.2.0 Installing xpath 3.2.0 Fetching capybara 3.12.0 Installing capybara 3.12.0 Fetching ffi 1.9.25 Installing ffi 1.9.25 with native extensions Fetching childprocess 0.9.0 Installing childprocess 0.9.0 Fetching chromedriver-helper 2.1.0 Installing chromedriver-helper 2.1.0 Fetching coderay 1.1.2 Installing coderay 1.1.2 Fetching coffee-script-source 1.11.1 Installing coffee-script-source 1.11.1 Fetching execjs 2.7.0 Installing execjs 2.7.0 Fetching coffee-script 2.4.1 Installing coffee-script 2.4.1 Fetching colorator 1.1.0 Installing colorator 1.1.0 Fetching colorize 0.8.1 Installing colorize 0.8.1 Fetching ruby-enum 0.7.2 Installing ruby-enum 0.7.2 Fetching commonmarker 0.17.13 Installing commonmarker 0.17.13 with native extensions Fetching diff-lcs 1.3 Installing diff-lcs 1.3 Fetching dnsruby 1.61.2 Installing dnsruby 1.61.2 Fetching eventmachine 1.2.7 Installing eventmachine 1.2.7 with native extensions Fetching http_parser.rb 0.6.0 Installing http_parser.rb 0.6.0 with native extensions Fetching em-websocket 0.5.1 Installing em-websocket 0.5.1 Fetching ethon 0.11.0 Installing ethon 0.11.0 Fetching multipart-post 2.0.0 Installing multipart-post 2.0.0 Fetching faraday 0.15.4 Installing faraday 0.15.4 Fetching forwardable-extended 2.6.0 Installing forwardable-extended 2.6.0 Fetching gemoji 3.0.0 Installing gemoji 3.0.0 Fetching sawyer 0.8.1 Installing sawyer 0.8.1 Fetching octokit 4.13.0 Installing octokit 4.13.0 Fetching typhoeus 1.3.1 Installing typhoeus 1.3.1 Fetching github-pages-health-check 1.8.1 Installing github-pages-health-check 1.8.1 Fetching rb-fsevent 0.10.3 Installing rb-fsevent 0.10.3 Fetching rb-inotify 0.9.10 Installing rb-inotify 0.9.10 Fetching sass-listen 4.0.0 Installing sass-listen 4.0.0 Fetching sass 3.7.2 Installing sass 3.7.2 Fetching jekyll-sass-converter 1.5.2 Installing jekyll-sass-converter 1.5.2 Fetching ruby_dep 1.5.0 Installing ruby_dep 1.5.0 Fetching listen 3.1.5 Installing listen 3.1.5 Fetching jekyll-watch 2.1.2 Installing jekyll-watch 2.1.2 Fetching kramdown 1.17.0 Installing kramdown 1.17.0 Fetching liquid 4.0.0 Installing liquid 4.0.0 Fetching mercenary 0.3.6 Installing mercenary 0.3.6 Fetching pathutil 0.16.2 Installing pathutil 0.16.2 Fetching rouge 2.2.1 Installing rouge 2.2.1 Fetching safe_yaml 1.0.4 Installing safe_yaml 1.0.4 Fetching jekyll 3.7.4 Installing jekyll 3.7.4 Fetching jekyll-avatar 0.6.0 Installing jekyll-avatar 0.6.0 Fetching jekyll-coffeescript 1.1.1 Installing jekyll-coffeescript 1.1.1 Fetching jekyll-commonmark 1.2.0 Installing jekyll-commonmark 1.2.0 Fetching jekyll-commonmark-ghpages 0.1.5 Installing jekyll-commonmark-ghpages 0.1.5 Fetching jekyll-default-layout 0.1.4 Installing jekyll-default-layout 0.1.4 Fetching jekyll-feed 0.11.0 Installing jekyll-feed 0.11.0 Fetching jekyll-gist 1.5.0 Installing jekyll-gist 1.5.0 Fetching jekyll-github-metadata 2.9.4 Installing jekyll-github-metadata 2.9.4 Fetching html-pipeline 2.9.1 Installing html-pipeline 2.9.1 Fetching jekyll-mentions 1.4.1 Installing jekyll-mentions 1.4.1 Fetching jekyll-optional-front-matter 0.3.0 Installing jekyll-optional-front-matter 0.3.0 Fetching jekyll-paginate 1.1.0 Installing jekyll-paginate 1.1.0 Fetching jekyll-readme-index 0.2.0 Installing jekyll-readme-index 0.2.0 Fetching jekyll-redirect-from 0.14.0 Installing jekyll-redirect-from 0.14.0 Fetching jekyll-relative-links 0.5.3 Installing jekyll-relative-links 0.5.3 Fetching rubyzip 1.2.2 Installing rubyzip 1.2.2 Fetching jekyll-remote-theme 0.3.1 Installing jekyll-remote-theme 0.3.1 Fetching jekyll-seo-tag 2.5.0 Installing jekyll-seo-tag 2.5.0 Fetching jekyll-sitemap 1.2.0 Installing jekyll-sitemap 1.2.0 Fetching jekyll-swiss 0.4.0 Installing jekyll-swiss 0.4.0 Fetching jekyll-theme-architect 0.1.1 Installing jekyll-theme-architect 0.1.1 Fetching jekyll-theme-cayman 0.1.1 Installing jekyll-theme-cayman 0.1.1 Fetching jekyll-theme-dinky 0.1.1 Installing jekyll-theme-dinky 0.1.1 Fetching jekyll-theme-hacker 0.1.1 Installing jekyll-theme-hacker 0.1.1 Fetching jekyll-theme-leap-day 0.1.1 Installing jekyll-theme-leap-day 0.1.1 Fetching jekyll-theme-merlot 0.1.1 Installing jekyll-theme-merlot 0.1.1 Fetching jekyll-theme-midnight 0.1.1 Installing jekyll-theme-midnight 0.1.1 Fetching jekyll-theme-minimal 0.1.1 Installing jekyll-theme-minimal 0.1.1 Fetching jekyll-theme-modernist 0.1.1 Installing jekyll-theme-modernist 0.1.1 Fetching jekyll-theme-primer 0.5.3 Installing jekyll-theme-primer 0.5.3 Fetching jekyll-theme-slate 0.1.1 Installing jekyll-theme-slate 0.1.1 Fetching jekyll-theme-tactile 0.1.1 Installing jekyll-theme-tactile 0.1.1 Fetching jekyll-theme-time-machine 0.1.1 Installing jekyll-theme-time-machine 0.1.1 Fetching jekyll-titles-from-headings 0.5.1 Installing jekyll-titles-from-headings 0.5.1 Fetching jemoji 0.10.1 Installing jemoji 0.10.1 Fetching minima 2.5.0 Installing minima 2.5.0 Fetching unicode-display_width 1.4.0 Installing unicode-display_width 1.4.0 Fetching terminal-table 1.8.0 Installing terminal-table 1.8.0 Fetching github-pages 193 Installing github-pages 193 Fetching parallel 1.12.1 Installing parallel 1.12.1 Fetching yell 2.0.7 Installing yell 2.0.7 Fetching html-proofer 3.9.3 Installing html-proofer 3.9.3 Fetching method_source 0.9.2 Installing method_source 0.9.2 Fetching pry 0.12.2 Installing pry 0.12.2 Fetching rack-jekyll 0.5.0 Installing rack-jekyll 0.5.0 Fetching rspec-support 3.8.0 Installing rspec-support 3.8.0 Fetching rspec-core 3.8.0 Installing rspec-core 3.8.0 Fetching rspec-expectations 3.8.2 Installing rspec-expectations 3.8.2 Fetching rspec-mocks 3.8.0 Installing rspec-mocks 3.8.0 Fetching rspec 3.8.0 Installing rspec 3.8.0 Fetching selenium-webdriver 3.141.0 Installing selenium-webdriver 3.141.0 Bundle complete! 8 Gemfile dependencies, 110 gems now installed. Bundled gems are installed into `/usr/local/bundle` ruby 2.5.3p105 (2018-10-18 revision 65156) [x86_64-linux-musl] Configuration file: /srv/jekyll/_config.yml Source: /srv/jekyll Destination: /srv/jekyll/_site Incremental build: disabled. Enable with --incremental Generating... jekyll 3.7.4 | Error: Permission denied @ dir_s_mkdir - /srv/jekyll/_site

[ghost]

On Thu, Dec 06, 2018 at 02:54:24PM -0800, Joe wrote: On Sat, Dec 01, 2018 at 05:23:21PM -0800, Justin W. Flory wrote: > @jwflory requested your review on: #35 Add development environment instructions > (closes #19). The error at the bottom goes away when I ```mkdir _site```

[...snip...]

Fetching rspec 3.8.0 Installing rspec 3.8.0 Fetching selenium-webdriver 3.141.0 Installing selenium-webdriver 3.141.0 Bundle complete! 8 Gemfile dependencies, 110 gems now installed. Bundled gems are installed into `/usr/local/bundle` ruby 2.5.3p105 (2018-10-18 revision 65156) [x86_64-linux-musl] Configuration file: /srv/jekyll/_config.yml Source: /srv/jekyll Destination: /srv/jekyll/_site Incremental build: disabled. Enable with --incremental Generating... jekyll 3.7.4 | Error: Permission denied @ dir_s_mkdir - /srv/jekyll/_site

By, "works" I mean this is what I get, and I get something at http://localhost:4000/ that looks like a website :-) ~/fossrit.github.io$ . start_devel_env.sh Fetching gem metadata from https://rubygems.org/......... Fetching concurrent-ruby 1.1.3 Installing concurrent-ruby 1.1.3 Fetching i18n 0.9.5 Installing i18n 0.9.5 Fetching minitest 5.11.3 Installing minitest 5.11.3 Fetching thread_safe 0.3.6 Installing thread_safe 0.3.6 Fetching tzinfo 1.2.5 Installing tzinfo 1.2.5 Fetching activesupport 4.2.10 Installing activesupport 4.2.10 Fetching public_suffix 2.0.5 Installing public_suffix 2.0.5 Fetching addressable 2.5.2 Installing addressable 2.5.2 Fetching io-like 0.3.0 Installing io-like 0.3.0 Fetching archive-zip 0.11.0 Installing archive-zip 0.11.0 Using bundler 1.17.1 Fetching mini_mime 1.0.1 Installing mini_mime 1.0.1 Fetching mini_portile2 2.3.0 Installing mini_portile2 2.3.0 Fetching nokogiri 1.8.5 Installing nokogiri 1.8.5 with native extensions Fetching rack 1.6.11 Installing rack 1.6.11 Fetching rack-test 1.1.0 Installing rack-test 1.1.0 Fetching regexp_parser 1.3.0 Installing regexp_parser 1.3.0 Fetching xpath 3.2.0 Installing xpath 3.2.0 Fetching capybara 3.12.0 Installing capybara 3.12.0 Fetching ffi 1.9.25 Installing ffi 1.9.25 with native extensions Fetching childprocess 0.9.0 Installing childprocess 0.9.0 Fetching chromedriver-helper 2.1.0 Installing chromedriver-helper 2.1.0 Fetching coderay 1.1.2 Installing coderay 1.1.2 Fetching coffee-script-source 1.11.1 Installing coffee-script-source 1.11.1 Fetching execjs 2.7.0 Installing execjs 2.7.0 Fetching coffee-script 2.4.1 Installing coffee-script 2.4.1 Fetching colorator 1.1.0 Installing colorator 1.1.0 Fetching colorize 0.8.1 Installing colorize 0.8.1 Fetching ruby-enum 0.7.2 Installing ruby-enum 0.7.2 Fetching commonmarker 0.17.13 Installing commonmarker 0.17.13 with native extensions Fetching diff-lcs 1.3 Installing diff-lcs 1.3 Fetching dnsruby 1.61.2 Installing dnsruby 1.61.2 Fetching eventmachine 1.2.7 Installing eventmachine 1.2.7 with native extensions Fetching http_parser.rb 0.6.0 Installing http_parser.rb 0.6.0 with native extensions Fetching em-websocket 0.5.1 Installing em-websocket 0.5.1 Fetching ethon 0.11.0 Installing ethon 0.11.0 Fetching multipart-post 2.0.0 Installing multipart-post 2.0.0 Fetching faraday 0.15.4 Installing faraday 0.15.4 Fetching forwardable-extended 2.6.0 Installing forwardable-extended 2.6.0 Fetching gemoji 3.0.0 Installing gemoji 3.0.0 Fetching sawyer 0.8.1 Installing sawyer 0.8.1 Fetching octokit 4.13.0 Installing octokit 4.13.0 Fetching typhoeus 1.3.1 Installing typhoeus 1.3.1 Fetching github-pages-health-check 1.8.1 Installing github-pages-health-check 1.8.1 Fetching rb-fsevent 0.10.3 Installing rb-fsevent 0.10.3 Fetching rb-inotify 0.9.10 Installing rb-inotify 0.9.10 Fetching sass-listen 4.0.0 Installing sass-listen 4.0.0 Fetching sass 3.7.2 Installing sass 3.7.2 Fetching jekyll-sass-converter 1.5.2 Installing jekyll-sass-converter 1.5.2 Fetching ruby_dep 1.5.0 Installing ruby_dep 1.5.0 Fetching listen 3.1.5 Installing listen 3.1.5 Fetching jekyll-watch 2.1.2 Installing jekyll-watch 2.1.2 Fetching kramdown 1.17.0 Installing kramdown 1.17.0 Fetching liquid 4.0.0 Installing liquid 4.0.0 Fetching mercenary 0.3.6 Installing mercenary 0.3.6 Fetching pathutil 0.16.2 Installing pathutil 0.16.2 Fetching rouge 2.2.1 Installing rouge 2.2.1 Fetching safe_yaml 1.0.4 Installing safe_yaml 1.0.4 Fetching jekyll 3.7.4 Installing jekyll 3.7.4 Fetching jekyll-avatar 0.6.0 Installing jekyll-avatar 0.6.0 Fetching jekyll-coffeescript 1.1.1 Installing jekyll-coffeescript 1.1.1 Fetching jekyll-commonmark 1.2.0 Installing jekyll-commonmark 1.2.0 Fetching jekyll-commonmark-ghpages 0.1.5 Installing jekyll-commonmark-ghpages 0.1.5 Fetching jekyll-default-layout 0.1.4 Installing jekyll-default-layout 0.1.4 Fetching jekyll-feed 0.11.0 Installing jekyll-feed 0.11.0 Fetching jekyll-gist 1.5.0 Installing jekyll-gist 1.5.0 Fetching jekyll-github-metadata 2.9.4 Installing jekyll-github-metadata 2.9.4 Fetching html-pipeline 2.9.1 Installing html-pipeline 2.9.1 Fetching jekyll-mentions 1.4.1 Installing jekyll-mentions 1.4.1 Fetching jekyll-optional-front-matter 0.3.0 Installing jekyll-optional-front-matter 0.3.0 Fetching jekyll-paginate 1.1.0 Installing jekyll-paginate 1.1.0 Fetching jekyll-readme-index 0.2.0 Installing jekyll-readme-index 0.2.0 Fetching jekyll-redirect-from 0.14.0 Installing jekyll-redirect-from 0.14.0 Fetching jekyll-relative-links 0.5.3 Installing jekyll-relative-links 0.5.3 Fetching rubyzip 1.2.2 Installing rubyzip 1.2.2 Fetching jekyll-remote-theme 0.3.1 Installing jekyll-remote-theme 0.3.1 Fetching jekyll-seo-tag 2.5.0 Installing jekyll-seo-tag 2.5.0 Fetching jekyll-sitemap 1.2.0 Installing jekyll-sitemap 1.2.0 Fetching jekyll-swiss 0.4.0 Installing jekyll-swiss 0.4.0 Fetching jekyll-theme-architect 0.1.1 Installing jekyll-theme-architect 0.1.1 Fetching jekyll-theme-cayman 0.1.1 Installing jekyll-theme-cayman 0.1.1 Fetching jekyll-theme-dinky 0.1.1 Installing jekyll-theme-dinky 0.1.1 Fetching jekyll-theme-hacker 0.1.1 Installing jekyll-theme-hacker 0.1.1 Fetching jekyll-theme-leap-day 0.1.1 Installing jekyll-theme-leap-day 0.1.1 Fetching jekyll-theme-merlot 0.1.1 Installing jekyll-theme-merlot 0.1.1 Fetching jekyll-theme-midnight 0.1.1 Installing jekyll-theme-midnight 0.1.1 Fetching jekyll-theme-minimal 0.1.1 Installing jekyll-theme-minimal 0.1.1 Fetching jekyll-theme-modernist 0.1.1 Installing jekyll-theme-modernist 0.1.1 Fetching jekyll-theme-primer 0.5.3 Installing jekyll-theme-primer 0.5.3 Fetching jekyll-theme-slate 0.1.1 Installing jekyll-theme-slate 0.1.1 Fetching jekyll-theme-tactile 0.1.1 Installing jekyll-theme-tactile 0.1.1 Fetching jekyll-theme-time-machine 0.1.1 Installing jekyll-theme-time-machine 0.1.1 Fetching jekyll-titles-from-headings 0.5.1 Installing jekyll-titles-from-headings 0.5.1 Fetching jemoji 0.10.1 Installing jemoji 0.10.1 Fetching minima 2.5.0 Installing minima 2.5.0 Fetching unicode-display_width 1.4.0 Installing unicode-display_width 1.4.0 Fetching terminal-table 1.8.0 Installing terminal-table 1.8.0 Fetching github-pages 193 Installing github-pages 193 Fetching parallel 1.12.1 Installing parallel 1.12.1 Fetching yell 2.0.7 Installing yell 2.0.7 Fetching html-proofer 3.9.3 Installing html-proofer 3.9.3 Fetching method_source 0.9.2 Installing method_source 0.9.2 Fetching pry 0.12.2 Installing pry 0.12.2 Fetching rack-jekyll 0.5.0 Installing rack-jekyll 0.5.0 Fetching rspec-support 3.8.0 Installing rspec-support 3.8.0 Fetching rspec-core 3.8.0 Installing rspec-core 3.8.0 Fetching rspec-expectations 3.8.2 Installing rspec-expectations 3.8.2 Fetching rspec-mocks 3.8.0 Installing rspec-mocks 3.8.0 Fetching rspec 3.8.0 Installing rspec 3.8.0 Fetching selenium-webdriver 3.141.0 Installing selenium-webdriver 3.141.0 Bundle complete! 8 Gemfile dependencies, 110 gems now installed. Bundled gems are installed into `/usr/local/bundle` ruby 2.5.3p105 (2018-10-18 revision 65156) [x86_64-linux-musl] Configuration file: /srv/jekyll/_config.yml Source: /srv/jekyll Destination: /srv/jekyll/_site Incremental build: disabled. Enable with --incremental Generating... done in 2.715 seconds. Auto-regeneration: enabled for '/srv/jekyll' Server address: http://0.0.0.0:4000 Server running... press ctrl-c to stop.

[ghost]

I can source the shell script to invoke it just fine: ```$ . start_devel_env.sh``` but if I give it execute permission via, eg, ```chmod u+x $ start_devel_env.sh``` and try to invoke it, I get an error due to Ubuntu not having yet jumped fully on the "shove everything that leaked into / over the last 40 years back into /usr" bandwagon as Fedora has done. Changing the hashbang line to /bin/bash works on Ubuntu, and my understanding is that it would work on Fedora et al too since they've retained the old locations as symlinks?

[jwflory]

I addressed @ritjoe's feedback in commit b9749e7. I'm merging this into the repo now. Thanks everyone for taking a look at this PR! 🎉