Add known-working Dockerfile including ruby/jekyll/submodule installation

[srstsavage]

@ocefpaf @MathewBiddle @mwengren Any thoughts? I struggled with getting a working local environment for a while due to ruby/glibc issues. Nice to have a portable Dockerfile spelling out the needed dependencies, env vars, etc.

[ocefpaf]

Definitely a plus IMO. I have a conda env for this that, when I accidentally remove it, it takes me ages to get it working again.

[mwengren]

Being able to run the Jekyll docs site via Docker would be a nice option. I haven't tried to run any of these sites locally for quite a while for the same reason. IIRC Docker may be documented in the upstream theme itself, as well.

My only question is can/should this be added to the https://github.com/ioos/ioos-documentation-jekyll-skeleton repo in addition to here?

[srstsavage]

Ah, yes, I see https://github.com/ioos/documentation-theme-jekyll/blob/main/Dockerfile (didn't test).

My only question is can/should this be added to the https://github.com/ioos/ioos-documentation-jekyll-skeleton repo in addition to here?

Definitley could be. Another option would be to host the bulk of the Dockerfile in its own repository and publish it to the IOOS Docker hub, and then inherit from that base image in specific projects. So the site local copy would turn into something like this:

FROM ioos/jekyll-base

COPY --chown=ubuntu:ubuntu Gemfile .

RUN bundle install
..
COPY --chown=ubuntu:ubuntu . .

RUN git submodule update --init

or maybe even just

FROM ioos/jekyll-base

using ONBUILD.

Would take a bit of setup effort, but then when the base image needs updating we wouldn't have to do it on every site repo.

[ocefpaf]

Definitley could be. Another option would be to host the bulk of the Dockerfile in its own repository and publish it to the IOOS Docker hub, and then inherit from that base image in specific projects.

+1 to that. We can set CIs to publish both on dockerhub and GitHub itself as redundancy.

[MathewBiddle]

One concern I have is we can't use docker on our government equipment. So, if I wanted to develop website content locally, I still have to install all the dependencies manually.

[ocefpaf]

One concern I have is we can't use docker on our government equipment. So, if I wanted to develop website content locally, I still have to install all the dependencies manually.

We should document how to get a local install too. I'm not sure how to do it in the "recommended way," I usually use a mix of conda and gem installs for that. This are my notes from my last installation in case someone wants to try and transform then into proper docs:

conda env create --name JEKYLL compilers "ruby<3"
gem update --system
gem install sass-embedded -v 1.63.6
gem install jekyll
gem install bundler
bundle install
ln -s ~/micromamba/envs/JEKYLL/bin/ruby ~/micromamba/envs/JEKYLL/share/rubygems/bin/ruby
bundle exec jekyll serve --config _config.yml,_config_dev.yml --watch

[mwengren]

Hi @ocefpaf We have that already, in full detail/start to finish, it's just not in the most finable place:

https://ioos.github.io/ioos-documentation-jekyll-skeleton/howto.html

An update to the layout of the jekyll-skeleton site to improve that would be welcome and would help for sure.

The index.md page contains dummy content on the homepage of the skeleton site.

https://github.com/ioos/ioos-documentation-jekyll-skeleton/blob/gh-pages/_docs/index.md

but then we have the howto.md that renders the above page:

https://github.com/ioos/ioos-documentation-jekyll-skeleton/blob/gh-pages/_docs/howto.md

Maybe we should just replace the index.md with the howto.md content and have that be the homepage?

There's also a link from the https://ioos.github.io/ to the howto instructions at the bottom of the sidebar menu.

I also haven't tested or followed those steps in a while like I mentioned. Hopefully all still works.

[srstsavage]

FWIW if we wanted to switch up the Dockerfile to use conda so that the steps are more directly useful to federal staff I'm not opposed. One of the major side benefits of a Dockerfile IMO is that it spells out in code explicitly which steps are needed for a known working build.

[ocefpaf]

@srstsavage I believe we could use both. The conda install instructions from above are not trivial, mix gems and conda packages, require a soft link to trick the installation, etc... I would use the docker image more than that.