From b436c0710bff8d1ae4b87ee9cbe108adb4378183 Mon Sep 17 00:00:00 2001 From: Pavan Date: Mon, 30 Mar 2026 16:27:46 -0700 Subject: [PATCH 1/7] [documentation / submitty.org] Containerize documentation site --- .dockerignore | 8 ++++++++ Dockerfile | 26 ++++++++++++++++++++++++++ README.md | 34 ++++++++++++++++++++++++++++++++++ docker-compose.yml | 15 +++++++++++++++ 4 files changed, 83 insertions(+) create mode 100644 .dockerignore create mode 100644 Dockerfile create mode 100644 docker-compose.yml diff --git a/.dockerignore b/.dockerignore new file mode 100644 index 00000000..c5e8aa32 --- /dev/null +++ b/.dockerignore @@ -0,0 +1,8 @@ +_site/ +.sass-cache/ +.jekyll-metadata +.git/ +.idea/ +*.iml +.DS_Store +vendor/ \ No newline at end of file diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 00000000..269062ae --- /dev/null +++ b/Dockerfile @@ -0,0 +1,26 @@ + +FROM ruby:3.2-slim + +# Install build dependencies required by native gem extensions (e.g., nokogiri) +# and libcurl for htmlproofer link checking +RUN apt-get update && \ + apt-get install -y --no-install-recommends \ + build-essential \ + git \ + libcurl4-openssl-dev \ + && rm -rf /var/lib/apt/lists/* + +WORKDIR /site + +# Install gems first (layer caching - only re-runs when Gemfile changes) +COPY Gemfile Gemfile.lock ./ +RUN bundle install + +# Copy the rest of the site +COPY . . + +EXPOSE 4000 + +# Serve the site, binding to 0.0.0.0 so it's accessible outside the container +CMD ["bundle", "exec", "jekyll", "serve", "--host", "0.0.0.0", "--livereload"] + \ No newline at end of file diff --git a/README.md b/README.md index e26d2eca..fbd3704c 100644 --- a/README.md +++ b/README.md @@ -20,6 +20,40 @@ For Bundler, depending on your system, you may need to also install the Ruby development headers (e.g. `ruby-dev`). On Ubuntu/Debian, for example, this would be accomplished by doing `sudo apt-get install ruby-dev`. + +### Docker Setup (Recommended) + +If you have [Docker](https://www.docker.com/) installed, you can skip +the Ruby/Bundler prerequisites entirely: + +1. Clone the repository: + ```bash + git clone https://github.com/Submitty/submitty.github.io.git + cd submitty.github.io + ``` +2. Start the development server: + ```bash + docker compose up + ``` + The first run takes a few minutes to install dependencies. Subsequent + runs start in seconds. + +3. Visit [http://localhost:4000](http://localhost:4000) to view the site. + Changes to files will automatically trigger a rebuild and refresh your + browser. + +4. To stop the server, press `Ctrl+C` or run: + ```bash + docker compose down + ``` + To run the link checker with Docker: + ```bash + docker compose exec docs bundle exec jekyll build + docker compose exec docs bundle exec htmlproofer ./_site --assume-extension --empty-alt-ignore --disable_external + ``` +If you prefer to set up Ruby natively, see the manual instructions below. + + ### Setup 1. Clone the respository on your local machine, e.g., diff --git a/docker-compose.yml b/docker-compose.yml new file mode 100644 index 00000000..8927eb96 --- /dev/null +++ b/docker-compose.yml @@ -0,0 +1,15 @@ +services: + docs: + build: . + ports: + - "4000:4000" + - "35729:35729" + volumes: + - .:/site + - bundle_cache:/usr/local/bundle + environment: + - JEKYLL_ENV=development + command: bundle exec jekyll serve --host 0.0.0.0 --livereload --force_polling + +volumes: + bundle_cache: \ No newline at end of file From fe63a3a026f466e8bab3d2a095418b23f6ee85ef Mon Sep 17 00:00:00 2001 From: roye2 <07eeroy@gmail.com> Date: Thu, 9 Jul 2026 16:56:06 -0400 Subject: [PATCH 2/7] use nginx as reverse proxy to manage requests between host and container --- Dockerfile | 5 ----- _docs/developer/getting_started/index.md | 2 +- docker-compose.yml | 16 ++++++++++++---- nginx.conf | 24 ++++++++++++++++++++++++ 4 files changed, 37 insertions(+), 10 deletions(-) create mode 100644 nginx.conf diff --git a/Dockerfile b/Dockerfile index 269062ae..3f0a3843 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,4 +1,3 @@ - FROM ruby:3.2-slim # Install build dependencies required by native gem extensions (e.g., nokogiri) @@ -20,7 +19,3 @@ RUN bundle install COPY . . EXPOSE 4000 - -# Serve the site, binding to 0.0.0.0 so it's accessible outside the container -CMD ["bundle", "exec", "jekyll", "serve", "--host", "0.0.0.0", "--livereload"] - \ No newline at end of file diff --git a/_docs/developer/getting_started/index.md b/_docs/developer/getting_started/index.md index 1a35e2f4..5903e08f 100644 --- a/_docs/developer/getting_started/index.md +++ b/_docs/developer/getting_started/index.md @@ -9,7 +9,7 @@ redirect_from: --- -Join our Community Discussion on Zulip: +Join our Community Discussion on Zulip [Contact Us](/contact) ## Setting Up diff --git a/docker-compose.yml b/docker-compose.yml index 8927eb96..02461c13 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -2,14 +2,22 @@ services: docs: build: . ports: - - "4000:4000" - - "35729:35729" + - "127.0.0.1:35729:35729" # livereload port, bypasses nginx + expose: + - "4000" volumes: - .:/site - bundle_cache:/usr/local/bundle environment: - JEKYLL_ENV=development command: bundle exec jekyll serve --host 0.0.0.0 --livereload --force_polling - + nginx: + image: nginx:alpine + ports: + - "127.0.0.1:4000:80" + volumes: + - ./nginx.conf:/etc/nginx/nginx.conf:ro + depends_on: + - docs volumes: - bundle_cache: \ No newline at end of file + bundle_cache: diff --git a/nginx.conf b/nginx.conf new file mode 100644 index 00000000..2140a0be --- /dev/null +++ b/nginx.conf @@ -0,0 +1,24 @@ +events {} +http { + server { + listen 80; + server_name localhost; + + sub_filter '0.0.0.0:4000' 'localhost:4000'; + sub_filter '0.0.0.0:35729' 'localhost:35729'; + sub_filter_once off; + sub_filter_types text/html application/json; + + location / { + proxy_pass http://docs:4000; + proxy_set_header Host $host; + } + + location /livereload { + proxy_pass http://docs:35729; + proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection "upgrade"; + } + } +} From 3aea9ef28a9474f895b3b556d6eca841d5f0f9e4 Mon Sep 17 00:00:00 2001 From: roye2 <07eeroy@gmail.com> Date: Thu, 9 Jul 2026 17:00:59 -0400 Subject: [PATCH 3/7] revert changees to developer index.md --- _docs/developer/getting_started/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_docs/developer/getting_started/index.md b/_docs/developer/getting_started/index.md index 5903e08f..1a35e2f4 100644 --- a/_docs/developer/getting_started/index.md +++ b/_docs/developer/getting_started/index.md @@ -9,7 +9,7 @@ redirect_from: --- -Join our Community Discussion on Zulip +Join our Community Discussion on Zulip: [Contact Us](/contact) ## Setting Up From 5ac2ad7499f8052e310893d6c4608a746b9f57bd Mon Sep 17 00:00:00 2001 From: roye2 <07eeroy@gmail.com> Date: Mon, 13 Jul 2026 10:19:17 -0400 Subject: [PATCH 4/7] force jekyll to use localhost:4000 with _config_docker.yml --- docker-compose.yml | 18 +++++------------- nginx.conf | 24 ------------------------ 2 files changed, 5 insertions(+), 37 deletions(-) delete mode 100644 nginx.conf diff --git a/docker-compose.yml b/docker-compose.yml index 02461c13..b115caeb 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -2,22 +2,14 @@ services: docs: build: . ports: - - "127.0.0.1:35729:35729" # livereload port, bypasses nginx - expose: - - "4000" + - "4000:4000" + - "35729:35729" volumes: - .:/site - bundle_cache:/usr/local/bundle environment: - - JEKYLL_ENV=development - command: bundle exec jekyll serve --host 0.0.0.0 --livereload --force_polling - nginx: - image: nginx:alpine - ports: - - "127.0.0.1:4000:80" - volumes: - - ./nginx.conf:/etc/nginx/nginx.conf:ro - depends_on: - - docs + - JEKYLL_ENV=docker + command: bundle exec jekyll serve --host 0.0.0.0 --livereload --force_polling --config _config.yml,_config_docker.yml + volumes: bundle_cache: diff --git a/nginx.conf b/nginx.conf deleted file mode 100644 index 2140a0be..00000000 --- a/nginx.conf +++ /dev/null @@ -1,24 +0,0 @@ -events {} -http { - server { - listen 80; - server_name localhost; - - sub_filter '0.0.0.0:4000' 'localhost:4000'; - sub_filter '0.0.0.0:35729' 'localhost:35729'; - sub_filter_once off; - sub_filter_types text/html application/json; - - location / { - proxy_pass http://docs:4000; - proxy_set_header Host $host; - } - - location /livereload { - proxy_pass http://docs:35729; - proxy_http_version 1.1; - proxy_set_header Upgrade $http_upgrade; - proxy_set_header Connection "upgrade"; - } - } -} From 8ab3a76236a39717af941287b5a86ad708ac2814 Mon Sep 17 00:00:00 2001 From: roye2 <07eeroy@gmail.com> Date: Mon, 13 Jul 2026 10:20:12 -0400 Subject: [PATCH 5/7] add _config_docker.yml --- _config_docker.yml | 1 + 1 file changed, 1 insertion(+) create mode 100644 _config_docker.yml diff --git a/_config_docker.yml b/_config_docker.yml new file mode 100644 index 00000000..8822b612 --- /dev/null +++ b/_config_docker.yml @@ -0,0 +1 @@ +url: "http://localhost:4000" From d6235ab403b8f3b4dcd06447e8b5fdd7ae8164fc Mon Sep 17 00:00:00 2001 From: roye2 <07eeroy@gmail.com> Date: Mon, 13 Jul 2026 11:03:10 -0400 Subject: [PATCH 6/7] update readme --- README.md | 57 ++++++++++++++++++++++------------------------ docker-compose.yml | 2 +- 2 files changed, 28 insertions(+), 31 deletions(-) diff --git a/README.md b/README.md index fbd3704c..7a7179a3 100644 --- a/README.md +++ b/README.md @@ -7,56 +7,53 @@ an open source course management, assignment submission, exam, and grading syste To report issues for this repository, please file them under the [Submitty/Submitty](https://github.com/Submitty/Submitty) repository. -## Local Development +## Local Development with Docker (Recommended) -### Prerequisites - -To develop the site locally, you will need to get the following dependencies: - -* [Ruby](https://www.ruby-lang.org/en/) -* [Bundler](https://bundler.io/) (`gem install bundler`) - -For Bundler, depending on your system, you may need to also install the -Ruby development headers (e.g. `ruby-dev`). On Ubuntu/Debian, -for example, this would be accomplished by doing `sudo apt-get install ruby-dev`. - - -### Docker Setup (Recommended) - -If you have [Docker](https://www.docker.com/) installed, you can skip -the Ruby/Bundler prerequisites entirely: +If you have [Docker](https://www.docker.com/) installed, you do not need to install Ruby or Bundler locally. 1. Clone the repository: ```bash git clone https://github.com/Submitty/submitty.github.io.git cd submitty.github.io ``` -2. Start the development server: +2. Start the development container: ```bash docker compose up ``` - The first run takes a few minutes to install dependencies. Subsequent - runs start in seconds. + The first run will take a few minutes to install dependencies. 3. Visit [http://localhost:4000](http://localhost:4000) to view the site. Changes to files will automatically trigger a rebuild and refresh your browser. -4. To stop the server, press `Ctrl+C` or run: +4. To stop the development container, press `Ctrl+C` or run: ```bash docker compose down ``` - To run the link checker with Docker: - ```bash - docker compose exec docs bundle exec jekyll build - docker compose exec docs bundle exec htmlproofer ./_site --assume-extension --empty-alt-ignore --disable_external - ``` -If you prefer to set up Ruby natively, see the manual instructions below. +### Running the link checker + +```bash +docker compose exec site bundle exec jekyll build +docker compose exec site bundle exec htmlproofer ./_site --assume-extension --empty-alt-ignore --disable_external +``` +Alternatively, you can develop the site with Ruby and Bundler installed locally. See the instructions below for more information. + +## Local Development with Ruby + +### Prerequisites + +To develop the site locally, you will need to get the following dependencies: + +* [Ruby](https://www.ruby-lang.org/en/) +* [Bundler](https://bundler.io/) (`gem install bundler`) +For Bundler, depending on your system, you may need to also install the +Ruby development headers (e.g. `ruby-dev`). On Ubuntu/Debian, +for example, this would be accomplished by doing `sudo apt-get install ruby-dev`. ### Setup -1. Clone the respository on your local machine, e.g., +1. Clone the repository on your local machine, e.g., ``` git clone https://github.com/Submitty/submitty.github.io.git @@ -163,11 +160,11 @@ above structure. Currently, the site only supports three levels of nesting (sub- ## Forked from [Edition](https://github.com/CloudCannon/edition-jekyll-template) This repository was created via a fork of Edition, which is a product documentation theme for Jekyll created -by by [CloudCannon](http://cloudcannon.com/), the Cloud CMS for Jekyll. +by [CloudCannon](http://cloudcannon.com/), the Cloud CMS for Jekyll. ### Ruby Version Troubleshooting In February 2024: -* https://ritviknag.com/tech-tips/ruby-versioning-hell-with-jekyll-&-github-pages/ \ No newline at end of file +* https://ritviknag.com/tech-tips/ruby-versioning-hell-with-jekyll-&-github-pages/ diff --git a/docker-compose.yml b/docker-compose.yml index b115caeb..837ad008 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -1,5 +1,5 @@ services: - docs: + site: build: . ports: - "4000:4000" From 3c6a41ff7651176848b8061f24d1a94a3da649df Mon Sep 17 00:00:00 2001 From: roye2 <07eeroy@gmail.com> Date: Mon, 13 Jul 2026 11:10:10 -0400 Subject: [PATCH 7/7] small formatting change --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index 7a7179a3..18ce5c5a 100644 --- a/README.md +++ b/README.md @@ -11,6 +11,8 @@ To report issues for this repository, please file them under the If you have [Docker](https://www.docker.com/) installed, you do not need to install Ruby or Bundler locally. +### Setup + 1. Clone the repository: ```bash git clone https://github.com/Submitty/submitty.github.io.git