Objective
Make it easier for users (like me) to contribute documentation updates for the Javalin web site.
REQUEST: Can the community provide a better Docker-based (or even non-Docker-based) approach for Windows users? See my attempt below.
Updates could be added to the readme page.
My Problem
When I recently submitted my first ever document change, I spent most of my time trying to set up a compatible Ruby/Jekyll environment with the correct set of gems, at the required versions to build the javalin.io site. This was definitely my problem, not related to the Javalin web site.
My main PC is Windows - which seems to have been at the root of my problems. See "alternatives" below for details.
Ideal Solution
I ended up using an updated dockerfile based on an older Jekyll Docker Container I found. I had to make some changes to that file. I have shared my end result below. But even with my modified dockerfile, the web site did not seem to build 100% correctly, locally - for example, the Java code on the home page does not have syntax highlighting (whereas the Kotlin code does - and Java code elsewhere seems OK).
So, I am not convinced that my Docker image is entirely correct - but it is good enough to be usable.
Perhaps the community can provide a better Docker-based (or even non-Docker-based) approach for Windows users? Clearly there are plenty of users who have been able to contribute to the Javalin documentation - probably without the struggle I had.
Maybe the end result could be added to the readme page. I would be happy to make that pull request myself, based on any feedback provided here.
Alternatives
Before I used my Docker approach, I tried:
- Chocolatey on Windows to install Ruby, Bundler and Jekyll. That led to many missing components.
- Ruby installer with devkit on Windows. That led to similar issues - especially with trying to compile native gems.
- A Linux-based approach (Amazon AMI2). That led to a failed Nokogiri build.
Even with the Docker approach, I had to experiment a bit with different Ruby versions. I failed to build the Javalin site using Ruby 3.1.3 - and ended up using Ruby 2.7.7.
My Dockerfile
This uses the Gemfile from copied from this GitHub project.
#
# An updated version of https://github.com/peteretelej/jekyll-container
#
FROM ruby:2.7.7-bullseye
RUN mkdir -p /etc/jekyll
COPY Gemfile /etc/jekyll
RUN apt-get -qq update && \
apt-get -qq install nodejs -y && \
gem install -q bundler -v 1.12.3 && \
bundle install --gemfile /etc/jekyll/Gemfile && \
apt-get clean && \
rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/*
ENV BUNDLE_GEMFILE /etc/jekyll/Gemfile
EXPOSE 4000
ENTRYPOINT ["bundle", "exec"]
CMD ["jekyll", "serve", "--host=0.0.0.0", "--future", "--incremental"]
Objective
Make it easier for users (like me) to contribute documentation updates for the Javalin web site.
REQUEST: Can the community provide a better Docker-based (or even non-Docker-based) approach for Windows users? See my attempt below.
Updates could be added to the readme page.
My Problem
When I recently submitted my first ever document change, I spent most of my time trying to set up a compatible Ruby/Jekyll environment with the correct set of gems, at the required versions to build the javalin.io site. This was definitely my problem, not related to the Javalin web site.
My main PC is Windows - which seems to have been at the root of my problems. See "alternatives" below for details.
Ideal Solution
I ended up using an updated dockerfile based on an older Jekyll Docker Container I found. I had to make some changes to that file. I have shared my end result below. But even with my modified dockerfile, the web site did not seem to build 100% correctly, locally - for example, the Java code on the home page does not have syntax highlighting (whereas the Kotlin code does - and Java code elsewhere seems OK).
So, I am not convinced that my Docker image is entirely correct - but it is good enough to be usable.
Perhaps the community can provide a better Docker-based (or even non-Docker-based) approach for Windows users? Clearly there are plenty of users who have been able to contribute to the Javalin documentation - probably without the struggle I had.
Maybe the end result could be added to the readme page. I would be happy to make that pull request myself, based on any feedback provided here.
Alternatives
Before I used my Docker approach, I tried:
Even with the Docker approach, I had to experiment a bit with different Ruby versions. I failed to build the Javalin site using Ruby 3.1.3 - and ended up using Ruby 2.7.7.
My Dockerfile
This uses the
Gemfilefrom copied from this GitHub project.