From e0d79a26c0791f1fd96fcd4933c1ac5a2cf32943 Mon Sep 17 00:00:00 2001 From: Oliver Eyton-Williams Date: Mon, 16 Nov 2020 15:03:18 +0100 Subject: [PATCH 01/28] feat: create docker dev environment --- .env | 2 ++ .gitignore | 1 + Dockerfile-dev | 40 ++++++++++++++++++++++++++++++++++++++++ docker-compose.yml | 13 +++++++++++++ 4 files changed, 56 insertions(+) create mode 100644 .env create mode 100644 Dockerfile-dev create mode 100644 docker-compose.yml diff --git a/.env b/.env new file mode 100644 index 0000000000..1a63eeffbb --- /dev/null +++ b/.env @@ -0,0 +1,2 @@ +USER_ID=1000 +GROUP_ID=1000 diff --git a/.gitignore b/.gitignore index 53bbb74575..6de43d6818 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,6 @@ .DS_Store .bundle +.bash_history log tmp public/assets diff --git a/Dockerfile-dev b/Dockerfile-dev new file mode 100644 index 0000000000..54f2f2e23d --- /dev/null +++ b/Dockerfile-dev @@ -0,0 +1,40 @@ +FROM ruby:2.6.5 + +ENV LANG=C.UTF-8 +ENV ENABLE_SERVICE_WORKER=true + +ARG USER_ID +ARG GROUP_ID + +RUN apt-get update && \ + apt-get -y install git nodejs libcurl4 && \ + gem install bundler + +# Create the dev user and set up a home dir +RUN if [ ${USER_ID:-0} -ne 0 ] && [ ${GROUP_ID:-0} -ne 0 ]; then \ + groupadd -g ${GROUP_ID} devuser &&\ + useradd -l -u ${USER_ID} -g devuser devuser &&\ + install -d -m 0755 -o devuser -g devuser /home/devuser &&\ + chown --changes --silent --no-dereference --recursive \ + --from=33:33 ${USER_ID}:${GROUP_ID} \ + /home/devuser \ + ;fi + +# Host directories cannot be mounted by Dockerfiles so we have to use +# a temporary directory to hold the lock files while the gems are installed. +WORKDIR /devdocs/ + +COPY Gemfile Gemfile.lock Rakefile /devdocs/ + +RUN bundle install && rm -rf /devdocs/ + +WORKDIR /home/devuser/ + +EXPOSE 9292 + +# This entrypoint lets you +# docker-compose run --rm --service-ports devdocs +# straight into a bash shell +ENTRYPOINT [ "/bin/bash" ] + +USER devuser diff --git a/docker-compose.yml b/docker-compose.yml new file mode 100644 index 0000000000..a9e07e11b4 --- /dev/null +++ b/docker-compose.yml @@ -0,0 +1,13 @@ +version: '3.7' +services: + devdocs: + build: + context: . + dockerfile: Dockerfile-dev + args: + USER_ID: ${USER_ID:-0} + GROUP_ID: ${GROUP_ID:-0} + volumes: + - ${PWD}:/home/devuser + ports: + - "9292:9292" From a8fd9e1e3633398ddcf7c57d664296fc0b3c8997 Mon Sep 17 00:00:00 2001 From: Oliver Eyton-Williams Date: Wed, 18 Nov 2020 12:17:37 +0100 Subject: [PATCH 02/28] feat: add devuser to sudoers --- Dockerfile-dev | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/Dockerfile-dev b/Dockerfile-dev index 54f2f2e23d..d4db5bb1ed 100644 --- a/Dockerfile-dev +++ b/Dockerfile-dev @@ -7,13 +7,15 @@ ARG USER_ID ARG GROUP_ID RUN apt-get update && \ - apt-get -y install git nodejs libcurl4 && \ + apt-get -y install git nodejs libcurl4 sudo && \ gem install bundler -# Create the dev user and set up a home dir +# Create the dev user, add them to sudoers and set up a home dir RUN if [ ${USER_ID:-0} -ne 0 ] && [ ${GROUP_ID:-0} -ne 0 ]; then \ groupadd -g ${GROUP_ID} devuser &&\ useradd -l -u ${USER_ID} -g devuser devuser &&\ + usermod -aG sudo devuser &&\ + echo '%sudo ALL=(ALL) NOPASSWD:ALL' >> /etc/sudoers &&\ install -d -m 0755 -o devuser -g devuser /home/devuser &&\ chown --changes --silent --no-dereference --recursive \ --from=33:33 ${USER_ID}:${GROUP_ID} \ From 5c7a9fecd6f8d8dd2fb1e51f25f17d3453996338 Mon Sep 17 00:00:00 2001 From: Oliver Eyton-Williams Date: Wed, 18 Nov 2020 14:45:01 +0100 Subject: [PATCH 03/28] docs: add Docker guide to CONTRIBUTING.md --- .github/CONTRIBUTING.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 21c112bb6b..61b54d347c 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -12,7 +12,8 @@ Want to contribute? Great. Please review the following guidelines carefully and 6. [Updating existing documentations](#updating-existing-documentations) 7. [Other contributions](#other-contributions) 8. [Coding conventions](#coding-conventions) -9. [Questions?](#questions) +9. [Developing in Docker](#developing-in-docker) +10. [Questions?](#questions) ## Reporting bugs From 8f1d402b23dc1ceff1af45777afd1597866d4a96 Mon Sep 17 00:00:00 2001 From: Oliver Eyton-Williams Date: Thu, 19 Nov 2020 09:27:25 +0100 Subject: [PATCH 04/28] fix: clarify which code is dev only Co-authored-by: Simon Legner --- .env | 2 -- .gitignore | 1 + docker-compose.yml => docker-compose.dev.yml | 0 sample.env | 4 ++++ 4 files changed, 5 insertions(+), 2 deletions(-) delete mode 100644 .env rename docker-compose.yml => docker-compose.dev.yml (100%) create mode 100644 sample.env diff --git a/.env b/.env deleted file mode 100644 index 1a63eeffbb..0000000000 --- a/.env +++ /dev/null @@ -1,2 +0,0 @@ -USER_ID=1000 -GROUP_ID=1000 diff --git a/.gitignore b/.gitignore index 6de43d6818..08f292c777 100644 --- a/.gitignore +++ b/.gitignore @@ -1,6 +1,7 @@ .DS_Store .bundle .bash_history +.env log tmp public/assets diff --git a/docker-compose.yml b/docker-compose.dev.yml similarity index 100% rename from docker-compose.yml rename to docker-compose.dev.yml diff --git a/sample.env b/sample.env new file mode 100644 index 0000000000..0715ce4ed3 --- /dev/null +++ b/sample.env @@ -0,0 +1,4 @@ +# Docker development config +USER_ID=1000 +GROUP_ID=1000 +COMPOSE_FILE=docker-compose.dev.yml From f1018d7ffddd516d8695e18e9be59baaabbd5697 Mon Sep 17 00:00:00 2001 From: Oliver Eyton-Williams Date: Thu, 19 Nov 2020 09:23:49 +0100 Subject: [PATCH 05/28] fix(docs): add missing Docker guide Co-authored-by: Simon Legner --- .github/CONTRIBUTING.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 61b54d347c..5e39628582 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -80,6 +80,23 @@ Follow the following steps to update documentations to their latest version: * no trailing whitespace; blank lines should have no spaces; new line at end-of-file * use the same coding style as the rest of the codebase +## Developing in Docker + +To set up a Docker development enviroment: + +1. Install [Docker](https://docs.docker.com/get-docker/) and [Docker Compose](https://docs.docker.com/compose/install/). +2. Navigate to the root of this repository. +3. `cp sample.env .env` +4. `docker-compose up -d` +5. `docker-compose run --rm --service-ports devdocs` + +You should now be in a bash shell inside the Docker container. The repo is mounted at `/home/devuser`, so any changes you make there will be reflected on the host (your machine) and vice versa. Commands can all be run inside the container: + +1. `thor docs:download --default` to get the default docs. +2. `rackup -o 0.0.0.0` to start the server + +Navigate to `http://localhost:9292` to see the running site. + ## Questions? If you have any questions, please feel free to ask them on the contributor chat room on [Gitter](https://gitter.im/FreeCodeCamp/DevDocs). From c1af9ce6abcac864f78429ef5e923ad59566e88a Mon Sep 17 00:00:00 2001 From: Oliver Eyton-Williams Date: Thu, 19 Nov 2020 13:29:47 +0100 Subject: [PATCH 06/28] fix: include attribution --- Dockerfile-dev | 2 ++ 1 file changed, 2 insertions(+) diff --git a/Dockerfile-dev b/Dockerfile-dev index d4db5bb1ed..423231c49c 100644 --- a/Dockerfile-dev +++ b/Dockerfile-dev @@ -11,6 +11,8 @@ RUN apt-get update && \ gem install bundler # Create the dev user, add them to sudoers and set up a home dir +# Adapted slightly from this excellent blog post: +# https://jtreminio.com/blog/running-docker-containers-as-current-host-user RUN if [ ${USER_ID:-0} -ne 0 ] && [ ${GROUP_ID:-0} -ne 0 ]; then \ groupadd -g ${GROUP_ID} devuser &&\ useradd -l -u ${USER_ID} -g devuser devuser &&\ From 8a035d923edbaeb5a2a66d89f336c38d964b5ebf Mon Sep 17 00:00:00 2001 From: Tyler Sengia Date: Fri, 21 Jun 2024 23:01:08 -0400 Subject: [PATCH 07/28] use multi-stage Dockerfile to reduce code --- Dockerfile | 45 +++++++++++++++++++++++++++++++++++---------- Dockerfile-alpine | 20 -------------------- Dockerfile-dev | 44 -------------------------------------------- 3 files changed, 35 insertions(+), 74 deletions(-) delete mode 100644 Dockerfile-alpine delete mode 100644 Dockerfile-dev diff --git a/Dockerfile b/Dockerfile index 848927d0b3..64f29ca817 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,24 +1,49 @@ -FROM ruby:3.3.2 +# +# Base layer that both dev and runtime inherit from. +# +FROM ruby:3.3.2-alpine as devdocs-base + ENV LANG=C.UTF-8 -ENV ENABLE_SERVICE_WORKER=true +ARG USERNAME=devdocs +ARG USER_ID=1000 +ARG GROUP_ID=1000 WORKDIR /devdocs - -RUN apt-get update && \ - apt-get -y install git nodejs libcurl4 && \ +EXPOSE 9292 + +RUN apk --update add nodejs build-base libstdc++ gzip git zlib-dev libcurl && \ gem install bundler && \ - rm -rf /var/lib/apt/lists/* + bundle config set path.system true && \ + bundle config set without test && \ + bundle install && \ + groupadd --gid $USER_GID $USERNAME && \ + useradd --uid $USER_UID --gid $USER_GID -m $USERNAME && \ + rm -rf /var/cache/apk/* ~/.gem /root/.bundle/cache \ + /usr/local/bundle/cache /usr/lib/node_modules -COPY Gemfile Gemfile.lock Rakefile /devdocs/ +COPY Gemfile Gemfile.lock Rakefile Thorfile /devdocs/ -RUN bundle install --system && \ +# +# Development Image +# +FROM devdocs-base as devdocs-dev +RUN bundle config unset without test && \ + bundle install && \ + apk add --update bash && \ rm -rf ~/.gem /root/.bundle/cache /usr/local/bundle/cache -COPY . /devdocs +USER $USERNAME +CMD bash +# +# Runtime Image +# +FROM devdocs-base as devdocs +ENV ENABLE_SERVICE_WORKER=true RUN thor docs:download --all && \ thor assets:compile && \ + apk del gzip build-base git zlib-dev && \ rm -rf /tmp -EXPOSE 9292 +USER $USERNAME CMD rackup -o 0.0.0.0 diff --git a/Dockerfile-alpine b/Dockerfile-alpine deleted file mode 100644 index 0e70a00da3..0000000000 --- a/Dockerfile-alpine +++ /dev/null @@ -1,20 +0,0 @@ -FROM ruby:3.3.2-alpine - -ENV LANG=C.UTF-8 -ENV ENABLE_SERVICE_WORKER=true - -WORKDIR /devdocs - -COPY . /devdocs - -RUN apk --update add nodejs build-base libstdc++ gzip git zlib-dev libcurl && \ - gem install bundler && \ - bundle install --system --without test && \ - thor docs:download --all && \ - thor assets:compile && \ - apk del gzip build-base git zlib-dev && \ - rm -rf /var/cache/apk/* /tmp ~/.gem /root/.bundle/cache \ - /usr/local/bundle/cache /usr/lib/node_modules - -EXPOSE 9292 -CMD rackup -o 0.0.0.0 diff --git a/Dockerfile-dev b/Dockerfile-dev deleted file mode 100644 index 423231c49c..0000000000 --- a/Dockerfile-dev +++ /dev/null @@ -1,44 +0,0 @@ -FROM ruby:2.6.5 - -ENV LANG=C.UTF-8 -ENV ENABLE_SERVICE_WORKER=true - -ARG USER_ID -ARG GROUP_ID - -RUN apt-get update && \ - apt-get -y install git nodejs libcurl4 sudo && \ - gem install bundler - -# Create the dev user, add them to sudoers and set up a home dir -# Adapted slightly from this excellent blog post: -# https://jtreminio.com/blog/running-docker-containers-as-current-host-user -RUN if [ ${USER_ID:-0} -ne 0 ] && [ ${GROUP_ID:-0} -ne 0 ]; then \ - groupadd -g ${GROUP_ID} devuser &&\ - useradd -l -u ${USER_ID} -g devuser devuser &&\ - usermod -aG sudo devuser &&\ - echo '%sudo ALL=(ALL) NOPASSWD:ALL' >> /etc/sudoers &&\ - install -d -m 0755 -o devuser -g devuser /home/devuser &&\ - chown --changes --silent --no-dereference --recursive \ - --from=33:33 ${USER_ID}:${GROUP_ID} \ - /home/devuser \ - ;fi - -# Host directories cannot be mounted by Dockerfiles so we have to use -# a temporary directory to hold the lock files while the gems are installed. -WORKDIR /devdocs/ - -COPY Gemfile Gemfile.lock Rakefile /devdocs/ - -RUN bundle install && rm -rf /devdocs/ - -WORKDIR /home/devuser/ - -EXPOSE 9292 - -# This entrypoint lets you -# docker-compose run --rm --service-ports devdocs -# straight into a bash shell -ENTRYPOINT [ "/bin/bash" ] - -USER devuser From 4309b44e403a67188227b266228ce02abfbb7793 Mon Sep 17 00:00:00 2001 From: Tyler Sengia Date: Fri, 21 Jun 2024 23:01:14 -0400 Subject: [PATCH 08/28] remove .env file --- sample.env | 4 ---- 1 file changed, 4 deletions(-) delete mode 100644 sample.env diff --git a/sample.env b/sample.env deleted file mode 100644 index 0715ce4ed3..0000000000 --- a/sample.env +++ /dev/null @@ -1,4 +0,0 @@ -# Docker development config -USER_ID=1000 -GROUP_ID=1000 -COMPOSE_FILE=docker-compose.dev.yml From f3e1f38f734bb841d28a45de3d6c7c86f46bb025 Mon Sep 17 00:00:00 2001 From: Tyler Sengia Date: Fri, 21 Jun 2024 23:01:23 -0400 Subject: [PATCH 09/28] create vscode devcontainer.json file --- .devcontainer/devcontainer.json | 9 +++++++++ 1 file changed, 9 insertions(+) create mode 100644 .devcontainer/devcontainer.json diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json new file mode 100644 index 0000000000..7174ae3969 --- /dev/null +++ b/.devcontainer/devcontainer.json @@ -0,0 +1,9 @@ +{ + "name": "DevDocs Dev Container", + "remoteUser": "devdocs", + "build": { + "context": "../", + "dockerfile": "../Dockerfile", + "target": "devdocs-dev" + } +} \ No newline at end of file From aec83bbe9e8c54b48f7818a747b0932c2574a02c Mon Sep 17 00:00:00 2001 From: Tyler Sengia Date: Sat, 22 Jun 2024 03:32:59 +0000 Subject: [PATCH 10/28] Add .gitattributes to work with Windows better --- .gitattributes | 1 + 1 file changed, 1 insertion(+) create mode 100644 .gitattributes diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000000..2125666142 --- /dev/null +++ b/.gitattributes @@ -0,0 +1 @@ +* text=auto \ No newline at end of file From f59abb9b8113e72ec2f409637407ee9ba76d9ebb Mon Sep 17 00:00:00 2001 From: Tyler Sengia Date: Sat, 22 Jun 2024 03:36:54 +0000 Subject: [PATCH 11/28] get devcontainer to work with VS Code --- .devcontainer/devcontainer.json | 16 +++++++++++----- Dockerfile | 20 ++++++++++++-------- 2 files changed, 23 insertions(+), 13 deletions(-) diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json index 7174ae3969..db11d695c0 100644 --- a/.devcontainer/devcontainer.json +++ b/.devcontainer/devcontainer.json @@ -1,9 +1,15 @@ { "name": "DevDocs Dev Container", - "remoteUser": "devdocs", - "build": { - "context": "../", - "dockerfile": "../Dockerfile", - "target": "devdocs-dev" + "image": "devdocs-dev:latest", + "customizations": { + "vscode": { + "extensions": [ + "Shopify.ruby-lsp", + "streetsidesoftware.code-spell-checker", + "mhutchie.git-graph", + "github.vscode-github-actions", + "ms-azuretools.vscode-docker" + ] + } } } \ No newline at end of file diff --git a/Dockerfile b/Dockerfile index 64f29ca817..9933313474 100644 --- a/Dockerfile +++ b/Dockerfile @@ -11,28 +11,32 @@ ARG GROUP_ID=1000 WORKDIR /devdocs EXPOSE 9292 + +COPY Gemfile Gemfile.lock Rakefile Thorfile /devdocs/ + RUN apk --update add nodejs build-base libstdc++ gzip git zlib-dev libcurl && \ - gem install bundler && \ + rm -rf /var/cache/apk/* /usr/lib/node_modules + +RUN gem install bundler && \ bundle config set path.system true && \ bundle config set without test && \ bundle install && \ - groupadd --gid $USER_GID $USERNAME && \ - useradd --uid $USER_UID --gid $USER_GID -m $USERNAME && \ - rm -rf /var/cache/apk/* ~/.gem /root/.bundle/cache \ - /usr/local/bundle/cache /usr/lib/node_modules + rm -rf ~/.gem /root/.bundle/cache /usr/local/bundle/cache -COPY Gemfile Gemfile.lock Rakefile Thorfile /devdocs/ +RUN addgroup -g $GROUP_ID $USERNAME && \ + adduser -u $USER_ID -G $USERNAME -D -h /devdocs $USERNAME && \ + chown -R $USERNAME:$USERNAME /devdocs # # Development Image # FROM devdocs-base as devdocs-dev -RUN bundle config unset without test && \ +RUN bundle config unset without && \ bundle install && \ apk add --update bash && \ rm -rf ~/.gem /root/.bundle/cache /usr/local/bundle/cache -USER $USERNAME +VOLUME [ "/devdocs" ] CMD bash # From 1220943548f13683cd4f690bd24a2aceb9289f9d Mon Sep 17 00:00:00 2001 From: Tyler Sengia Date: Sat, 22 Jun 2024 15:57:20 +0000 Subject: [PATCH 12/28] Remove compose file --- docker-compose.dev.yml | 13 ------------- 1 file changed, 13 deletions(-) delete mode 100644 docker-compose.dev.yml diff --git a/docker-compose.dev.yml b/docker-compose.dev.yml deleted file mode 100644 index a9e07e11b4..0000000000 --- a/docker-compose.dev.yml +++ /dev/null @@ -1,13 +0,0 @@ -version: '3.7' -services: - devdocs: - build: - context: . - dockerfile: Dockerfile-dev - args: - USER_ID: ${USER_ID:-0} - GROUP_ID: ${GROUP_ID:-0} - volumes: - - ${PWD}:/home/devuser - ports: - - "9292:9292" From 2fb2b2776ce1285d9e05cc11697917fb39af841c Mon Sep 17 00:00:00 2001 From: Tyler Sengia Date: Sat, 22 Jun 2024 15:57:40 +0000 Subject: [PATCH 13/28] Get docker-from-docker working with VS Code --- .devcontainer/devcontainer.json | 6 ++++-- Dockerfile | 8 ++++++-- 2 files changed, 10 insertions(+), 4 deletions(-) diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json index db11d695c0..77216f0173 100644 --- a/.devcontainer/devcontainer.json +++ b/.devcontainer/devcontainer.json @@ -1,6 +1,6 @@ { "name": "DevDocs Dev Container", - "image": "devdocs-dev:latest", + "image": "devdocs-dev:0.0.1", "customizations": { "vscode": { "extensions": [ @@ -11,5 +11,7 @@ "ms-azuretools.vscode-docker" ] } - } + }, + "mounts": ["source=/var/run/docker.sock,target=/var/run/docker.sock,type=bind"], + "appPort": 9292 } \ No newline at end of file diff --git a/Dockerfile b/Dockerfile index 9933313474..f916e80839 100644 --- a/Dockerfile +++ b/Dockerfile @@ -33,8 +33,12 @@ RUN addgroup -g $GROUP_ID $USERNAME && \ FROM devdocs-base as devdocs-dev RUN bundle config unset without && \ bundle install && \ - apk add --update bash && \ - rm -rf ~/.gem /root/.bundle/cache /usr/local/bundle/cache + apk add --update bash curl && \ + curl -LO https://download.docker.com/linux/static/stable/x86_64/docker-26.1.4.tgz && \ + tar -xzf docker-26.1.4.tgz && \ + mv docker/docker /usr/bin && \ + rm -rf docker docker-26.1.4.tgz && \ + rm -rf ~/.gem /root/.bundle/cache /usr/local/bundle/cache VOLUME [ "/devdocs" ] CMD bash From 69c8f1f52e13fd1e7aba0cbe7b75ae20ac281a65 Mon Sep 17 00:00:00 2001 From: Tyler Sengia Date: Sat, 22 Jun 2024 16:17:24 +0000 Subject: [PATCH 14/28] ignore already downloaded docs when building docker image --- .dockerignore | 1 + 1 file changed, 1 insertion(+) diff --git a/.dockerignore b/.dockerignore index 64b8f28ccf..3b41a9a952 100644 --- a/.dockerignore +++ b/.dockerignore @@ -5,3 +5,4 @@ Dockerfile* .dockerignore .travis.yml *.md +public/docs/* \ No newline at end of file From 7f8aa22e1e5767f377deaffd4d758daea4134da2 Mon Sep 17 00:00:00 2001 From: Tyler Sengia Date: Sat, 22 Jun 2024 16:50:47 +0000 Subject: [PATCH 15/28] make downloaded docs a docker volume --- .devcontainer/devcontainer.json | 5 ++++- Dockerfile | 5 +++-- 2 files changed, 7 insertions(+), 3 deletions(-) diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json index 77216f0173..037d0c6cfe 100644 --- a/.devcontainer/devcontainer.json +++ b/.devcontainer/devcontainer.json @@ -12,6 +12,9 @@ ] } }, - "mounts": ["source=/var/run/docker.sock,target=/var/run/docker.sock,type=bind"], + "mounts": [ + {"source":"/var/run/docker.sock","target":"/var/run/docker.sock","type": "bind"}, + {"source": "devdocs-downloaded","target": "/devdocs/public/docs","type": "volume"} + ], "appPort": 9292 } \ No newline at end of file diff --git a/Dockerfile b/Dockerfile index f916e80839..8d4588b56f 100644 --- a/Dockerfile +++ b/Dockerfile @@ -48,10 +48,11 @@ CMD bash # FROM devdocs-base as devdocs ENV ENABLE_SERVICE_WORKER=true -RUN thor docs:download --all && \ - thor assets:compile && \ +COPY . /devdocs/ +RUN thor assets:compile && \ apk del gzip build-base git zlib-dev && \ rm -rf /tmp +VOLUME ["/devdocs/public/docs"] USER $USERNAME CMD rackup -o 0.0.0.0 From da5a924f84e8bfa9c0503d1a93f42d298a02d4f2 Mon Sep 17 00:00:00 2001 From: Tyler Sengia Date: Sat, 22 Jun 2024 23:28:34 +0000 Subject: [PATCH 16/28] dynamically get docs origin and production host instead of hard coding --- assets/javascripts/app/config.js.erb | 4 ++-- views/index.erb | 2 ++ 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/assets/javascripts/app/config.js.erb b/assets/javascripts/app/config.js.erb index 56ce26522f..f27efa4eb6 100644 --- a/assets/javascripts/app/config.js.erb +++ b/assets/javascripts/app/config.js.erb @@ -1,13 +1,13 @@ app.config = { db_filename: 'db.json', default_docs: <%= App.default_docs.to_json %>, - docs_origin: '<%= App.docs_origin %>', + docs_origin: document.getElementById("docs-origin-meta").content, env: '<%= App.environment %>', history_cache_size: 10, index_filename: 'index.json', index_path: '/<%= App.docs_prefix %>', max_results: 50, - production_host: 'devdocs.io', + production_host: document.getElementById("production-host-meta").content, search_param: 'q', sentry_dsn: '<%= App.sentry_dsn %>', version: <%= Time.now.to_i %>, diff --git a/views/index.erb b/views/index.erb index 428dc705a9..f7146dc6da 100644 --- a/views/index.erb +++ b/views/index.erb @@ -21,6 +21,8 @@ + + DevDocs API Documentation From 9526ddf6016d03a57a5f9db8c1cf177395f32e17 Mon Sep 17 00:00:00 2001 From: Tyler Sengia Date: Sat, 22 Jun 2024 23:29:02 +0000 Subject: [PATCH 17/28] changes to get local deployment working --- lib/app.rb | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/lib/app.rb b/lib/app.rb index e23b241c06..b5a2324cec 100644 --- a/lib/app.rb +++ b/lib/app.rb @@ -12,7 +12,10 @@ class App < Sinatra::Application Rack::Mime::MIME_TYPES['.webapp'] = 'application/x-web-app-manifest+json' configure do - use Rack::SslEnforcer, only_environments: ['production', 'test'], hsts: true, force_secure_cookies: false + + unless ENV.has_key?('DEVDOCS_DISABLE_SSL') + use Rack::SslEnforcer, only_environments: ['production', 'test'], hsts: !ENV.has_key?('DEVDOCS_DISABLE_HSTS'), force_secure_cookies: false + end set :sentry_dsn, ENV['SENTRY_DSN'] set :protection, except: [:frame_options, :xss_header] @@ -26,6 +29,7 @@ class App < Sinatra::Application set :assets_compile, %w(*.png docs.js docs.json application.js application.css application-dark.css) require 'yajl/json_gem' + set :docs_host, ENV.fetch("DEVDOCS_HOST", "devdocs.io") set :docs_prefix, 'docs' set :docs_origin, File.join('', docs_prefix) set :docs_path, File.join(public_folder, docs_prefix) @@ -72,7 +76,7 @@ class App < Sinatra::Application configure :production do set :static, false - set :docs_origin, '//documents.devdocs.io' + set :docs_origin, "//" + ENV.fetch("DEVDOCS_DOCS_ORIGIN", "documents.devdocs.io") set :csp, "default-src 'self' *; script-src 'self' 'nonce-devdocs' https://www.google-analytics.com https://secure.gaug.es https://*.jquery.com; font-src 'none'; style-src 'self' 'unsafe-inline' *; img-src 'self' * data:;" use Rack::ConditionalGet @@ -125,8 +129,8 @@ def self.parse_news end configure :production do - set :docs, parse_docs - set :news, parse_news + set :docs, -> { parse_docs } + set :news, -> { parse_news } end helpers do @@ -421,8 +425,10 @@ def modern_browser?(browser) redirect "/#{doc}#{type}/#{query_string_for_redirection}" elsif rest.length > 1 && rest.end_with?('/') redirect "/#{doc}#{type}#{rest[0...-1]}#{query_string_for_redirection}" - elsif user_has_docs?(doc) && supports_js_redirection? + elsif !request.path.end_with?(".html") && user_has_docs?(doc) && supports_js_redirection? redirect_via_js(request.path) + elsif File.exist?(File.join(settings.public_folder, "docs", request.path.gsub("..",""))) + send_file File.join(settings.public_folder, "docs", request.path.gsub("..","")), status: status else response.headers['Content-Security-Policy'] = settings.csp if settings.csp erb :other From 45f80ae0e42cef2162302e7e0e1f13f0175c73be Mon Sep 17 00:00:00 2001 From: Tyler Sengia Date: Sat, 22 Jun 2024 23:37:12 +0000 Subject: [PATCH 18/28] fixed referencing wrong variable name --- views/index.erb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/views/index.erb b/views/index.erb index f7146dc6da..5c268f7b25 100644 --- a/views/index.erb +++ b/views/index.erb @@ -21,7 +21,7 @@ - + DevDocs API Documentation From a1936a2570144c55d14c969e3b3cb2690e7ea2c5 Mon Sep 17 00:00:00 2001 From: Tyler Sengia Date: Sat, 22 Jun 2024 23:38:54 +0000 Subject: [PATCH 19/28] Set production docker container CMD --- Dockerfile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Dockerfile b/Dockerfile index 8d4588b56f..d22da04909 100644 --- a/Dockerfile +++ b/Dockerfile @@ -55,4 +55,4 @@ RUN thor assets:compile && \ VOLUME ["/devdocs/public/docs"] USER $USERNAME -CMD rackup -o 0.0.0.0 +CMD rackup --host 0.0.0.0 -E production From dfadd7864ce6ee7e4dd3441f698f16eb515b55bb Mon Sep 17 00:00:00 2001 From: Tyler Sengia Date: Sun, 23 Jun 2024 16:11:10 +0000 Subject: [PATCH 20/28] switch to building docker image with all docs downloaded --- .dockerignore | 7 ++++++- Dockerfile | 6 +++--- README.md | 32 +++++++++++++++++++++++++------- 3 files changed, 34 insertions(+), 11 deletions(-) diff --git a/.dockerignore b/.dockerignore index 3b41a9a952..0a0fd556eb 100644 --- a/.dockerignore +++ b/.dockerignore @@ -5,4 +5,9 @@ Dockerfile* .dockerignore .travis.yml *.md -public/docs/* \ No newline at end of file +public/docs/* +public/assets/* +log/* +tmp/* +test/* +.bash_history \ No newline at end of file diff --git a/Dockerfile b/Dockerfile index d22da04909..acd726dd32 100644 --- a/Dockerfile +++ b/Dockerfile @@ -49,10 +49,10 @@ CMD bash FROM devdocs-base as devdocs ENV ENABLE_SERVICE_WORKER=true COPY . /devdocs/ -RUN thor assets:compile && \ +RUN thor docs:download --all && \ + thor assets:compile && \ apk del gzip build-base git zlib-dev && \ rm -rf /tmp - -VOLUME ["/devdocs/public/docs"] +RUN chown -R $USERNAME:$USERNAME /devdocs USER $USERNAME CMD rackup --host 0.0.0.0 -E production diff --git a/README.md b/README.md index a54f4992ee..6e7cf012f3 100644 --- a/README.md +++ b/README.md @@ -38,17 +38,35 @@ The `thor docs:download` command is used to download pre-generated documentation **Note:** there is currently no update mechanism other than `git pull origin main` to update the code and `thor docs:download --installed` to download the latest version of the docs. To stay informed about new releases, be sure to [watch](https://github.com/freeCodeCamp/devdocs/subscription) this repository. -Alternatively, DevDocs may be started as a Docker container: +## Deploying via Docker +The DevDocs server may also be deployed as a Docker container: ```sh -# First, build the image -git clone https://github.com/freeCodeCamp/devdocs.git && cd devdocs -docker build -t thibaut/devdocs . - -# Finally, start a DevDocs container (access http://localhost:9292) -docker run --name devdocs -d -p 9292:9292 thibaut/devdocs +# First, pull the image +docker pull devdocs/devdocs + +# Start the DevDocs container (accessible at http://localhost:9292) +docker run \ + -e DEVDOCS_DISABLE_SSL \ + -e DEVDOCS_DOCS_ORIGIN=localhost:9292 \ + -e DEVDOCS_HOST=localhost:9292 \ + -p 9292:9292 \ + devdocs/devdocs ``` +There are multiple environment variables that you can set to consider the DevDocs server. + +These can be useful when deploying DevDocs behind a reverse proxy or on your own offline network. + +| Environment Variable | Default Value | Description | +|---------------------:|:---------------------|:------------------------------------------------------------------------------------------------| +|`DEVDOCS_DISABLE_SSL` |Not defined | Define this variable to disable HTTPS redirect. | +|`DEVDOCS_HOST` |`devdocs.io` | Hostname that is serving the DevDocs application. | +|`DEVDOCS_DOCS_ORIGIN` |`documents.devdocs.io`| Hostname that is serving the DevDocs documentation pages. | +|`DEVDOCS_DISABLE_HSTS`|Not defined | Define this variable to disable HSTS. If `DEVDOCS_DISABLE_SSL` is defined then this is implied. | + + + ## Vision DevDocs aims to make reading and searching reference documentation fast, easy and enjoyable. From d83e30b38c98f8beb885f7eca6b05abce69802c1 Mon Sep 17 00:00:00 2001 From: Tyler Sengia Date: Sun, 23 Jun 2024 19:26:41 +0000 Subject: [PATCH 21/28] Get offline runtime docker image to work --- Dockerfile | 9 ++++----- README.md | 19 +++++++++++++++++-- 2 files changed, 21 insertions(+), 7 deletions(-) diff --git a/Dockerfile b/Dockerfile index acd726dd32..beceada35d 100644 --- a/Dockerfile +++ b/Dockerfile @@ -40,7 +40,7 @@ RUN bundle config unset without && \ rm -rf docker docker-26.1.4.tgz && \ rm -rf ~/.gem /root/.bundle/cache /usr/local/bundle/cache -VOLUME [ "/devdocs" ] +VOLUME [ "/devdocs", "/devdocs/public/docs", "/devdocs/public/assets" ] CMD bash # @@ -49,10 +49,9 @@ CMD bash FROM devdocs-base as devdocs ENV ENABLE_SERVICE_WORKER=true COPY . /devdocs/ -RUN thor docs:download --all && \ - thor assets:compile && \ - apk del gzip build-base git zlib-dev && \ +RUN apk del gzip build-base git zlib-dev && \ + chown -R $USERNAME:$USERNAME /devdocs && \ rm -rf /tmp -RUN chown -R $USERNAME:$USERNAME /devdocs +VOLUME [ "/devdocs/public/docs", "/devdocs/public/assets" ] USER $USERNAME CMD rackup --host 0.0.0.0 -E production diff --git a/README.md b/README.md index 6e7cf012f3..cecd0ffb6b 100644 --- a/README.md +++ b/README.md @@ -45,8 +45,22 @@ The DevDocs server may also be deployed as a Docker container: # First, pull the image docker pull devdocs/devdocs +# Next, download documentation that you want, this example downloads the ruby docs. +docker run --rm \ + -v devdocs-docs:/devdocs/public/docs \ + -v devdocs-assets:/devdocs/public/assets \ + devdocs/devdocs thor docs:download ruby + +# Now compile the assets. This must be done after you download all the documentation you want. +docker run --rm \ + -v devdocs-docs:/devdocs/public/docs \ + -v devdocs-assets:/devdocs/public/assets \ + devdocs/devdocs thor assets:compile + # Start the DevDocs container (accessible at http://localhost:9292) docker run \ + -v devdocs-docs:/devdocs/public/docs \ + -v devdocs-assets:/devdocs/public/assets \ -e DEVDOCS_DISABLE_SSL \ -e DEVDOCS_DOCS_ORIGIN=localhost:9292 \ -e DEVDOCS_HOST=localhost:9292 \ @@ -54,7 +68,9 @@ docker run \ devdocs/devdocs ``` -There are multiple environment variables that you can set to consider the DevDocs server. +The `devdocs-docs` and `devdocs-assets` volumes contain the downloaded documentation and static site data used by the server. + +There are multiple environment variables that you can set to configure the DevDocs server. These can be useful when deploying DevDocs behind a reverse proxy or on your own offline network. @@ -66,7 +82,6 @@ These can be useful when deploying DevDocs behind a reverse proxy or on your own |`DEVDOCS_DISABLE_HSTS`|Not defined | Define this variable to disable HSTS. If `DEVDOCS_DISABLE_SSL` is defined then this is implied. | - ## Vision DevDocs aims to make reading and searching reference documentation fast, easy and enjoyable. From 3dfd66e89cc48fd5bd44e2e2e3c5ee80de191a6f Mon Sep 17 00:00:00 2001 From: Tyler Sengia Date: Mon, 24 Jun 2024 01:02:20 +0000 Subject: [PATCH 22/28] switch to build based devcontainer --- .devcontainer/devcontainer.json | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json index 037d0c6cfe..6b48a297ac 100644 --- a/.devcontainer/devcontainer.json +++ b/.devcontainer/devcontainer.json @@ -1,6 +1,10 @@ { "name": "DevDocs Dev Container", - "image": "devdocs-dev:0.0.1", + "build": { + "context": "../", + "dockerfile": "../Dockerfile", + "target": "devdocs-dev" + }, "customizations": { "vscode": { "extensions": [ From cf708b21fc76a88b81f2c8442e071666bbbb1735 Mon Sep 17 00:00:00 2001 From: Tyler Sengia Date: Mon, 24 Jun 2024 01:10:24 +0000 Subject: [PATCH 23/28] Add oxipng --- Dockerfile | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/Dockerfile b/Dockerfile index beceada35d..96a72f6689 100644 --- a/Dockerfile +++ b/Dockerfile @@ -10,11 +10,10 @@ ARG USER_ID=1000 ARG GROUP_ID=1000 WORKDIR /devdocs EXPOSE 9292 - COPY Gemfile Gemfile.lock Rakefile Thorfile /devdocs/ -RUN apk --update add nodejs build-base libstdc++ gzip git zlib-dev libcurl && \ +RUN apk --update add nodejs build-base libstdc++ gzip git zlib-dev libcurl oxipng && \ rm -rf /var/cache/apk/* /usr/lib/node_modules RUN gem install bundler && \ From 153d4e6b4e1b7c3f4ef7200e280c5aff8b85a9ad Mon Sep 17 00:00:00 2001 From: Tyler Sengia Date: Mon, 24 Jun 2024 01:10:40 +0000 Subject: [PATCH 24/28] Add steps to build the runtime docker image --- README.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/README.md b/README.md index cecd0ffb6b..bd1b4d6e07 100644 --- a/README.md +++ b/README.md @@ -81,6 +81,10 @@ These can be useful when deploying DevDocs behind a reverse proxy or on your own |`DEVDOCS_DOCS_ORIGIN` |`documents.devdocs.io`| Hostname that is serving the DevDocs documentation pages. | |`DEVDOCS_DISABLE_HSTS`|Not defined | Define this variable to disable HSTS. If `DEVDOCS_DISABLE_SSL` is defined then this is implied. | +To build the image fresh, use the below command: +```bash +docker build . -t devdocs/devdocs --target devdocs +``` ## Vision From d3457948a83fb64435e7694b373ecefa8ff178a6 Mon Sep 17 00:00:00 2001 From: Tyler Sengia Date: Mon, 24 Jun 2024 01:21:22 +0000 Subject: [PATCH 25/28] Update docker commands with more examples --- README.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index bd1b4d6e07..87927d59fc 100644 --- a/README.md +++ b/README.md @@ -45,11 +45,13 @@ The DevDocs server may also be deployed as a Docker container: # First, pull the image docker pull devdocs/devdocs -# Next, download documentation that you want, this example downloads the ruby docs. +# Next, download documentation that you want, this example downloads the default set of docs, and the ruby docs. +# Use: --default to download the default set of docs +# Use: --all to download ALL available docs (WARNING: Will take a long time!) docker run --rm \ -v devdocs-docs:/devdocs/public/docs \ -v devdocs-assets:/devdocs/public/assets \ - devdocs/devdocs thor docs:download ruby + devdocs/devdocs thor docs:download --default ruby # Now compile the assets. This must be done after you download all the documentation you want. docker run --rm \ From 3c191029347c6d46b31371ed428d763251d03786 Mon Sep 17 00:00:00 2001 From: Tyler Sengia Date: Mon, 24 Jun 2024 01:25:30 +0000 Subject: [PATCH 26/28] add EditorConfig extension, add code spell words --- .devcontainer/devcontainer.json | 8 ++++---- .vscode/settings.json | 6 ++++++ 2 files changed, 10 insertions(+), 4 deletions(-) create mode 100644 .vscode/settings.json diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json index 6b48a297ac..fa7e364ea6 100644 --- a/.devcontainer/devcontainer.json +++ b/.devcontainer/devcontainer.json @@ -3,16 +3,16 @@ "build": { "context": "../", "dockerfile": "../Dockerfile", - "target": "devdocs-dev" + "target": "devdocs-dev" }, "customizations": { "vscode": { "extensions": [ - "Shopify.ruby-lsp", "streetsidesoftware.code-spell-checker", "mhutchie.git-graph", "github.vscode-github-actions", - "ms-azuretools.vscode-docker" + "ms-azuretools.vscode-docker", + "EditorConfig.EditorConfig" ] } }, @@ -21,4 +21,4 @@ {"source": "devdocs-downloaded","target": "/devdocs/public/docs","type": "volume"} ], "appPort": 9292 -} \ No newline at end of file +} diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 0000000000..80b1c05bb7 --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,6 @@ +{ + "cSpell.words": [ + "devdocs", + "rackup" + ] +} From 769e9d206a0961d94ed95d36cf1a1fa8da591e7d Mon Sep 17 00:00:00 2001 From: Tyler Sengia Date: Mon, 24 Jun 2024 01:28:47 +0000 Subject: [PATCH 27/28] clean up before PR --- .github/CONTRIBUTING.md | 18 ------------------ 1 file changed, 18 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 0d2b54513d..fc0dac2e3d 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -79,27 +79,9 @@ Follow the following steps to update documentations to their latest version: * no trailing whitespace; blank lines should have no spaces; new line at end-of-file * use the same coding style as the rest of the codebase - These conventions are formalized in [our `.editorconfig` file](../.editorconfig). Check out [EditorConfig.org](https://editorconfig.org/) to learn how to make your tools adhere to it. -### Developing in Docker - -To set up a Docker development environment: - -1. Install [Docker](https://docs.docker.com/get-docker/) and [Docker Compose](https://docs.docker.com/compose/install/). -2. Navigate to the root of this repository. -3. `cp sample.env .env` -4. `docker-compose up -d` -5. `docker-compose run --rm --service-ports devdocs` - -You should now be in a bash shell inside the Docker container. The repo is mounted at `/home/devuser`, so any changes you make there will be reflected on the host (your machine) and vice versa. Commands can all be run inside the container: - -1. `thor docs:download --default` to get the default docs. -2. `rackup -o 0.0.0.0` to start the server - -Navigate to `http://localhost:9292` to see the running site. - ## Questions? If you have any questions, please feel free to ask them on the contributor chat room on [Discord](https://discord.gg/PRyKn3Vbay). From 3b25a1090c0cb6938efd7fc50857326d216ffa3e Mon Sep 17 00:00:00 2001 From: Tyler Sengia Date: Fri, 28 Jun 2024 00:41:55 +0000 Subject: [PATCH 28/28] Remove // from docs origin settings and only serve docs pages from app server if docs origin and app host are the same --- assets/javascripts/models/doc.js | 4 ++-- lib/app.rb | 4 ++-- views/index.erb | 2 +- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/assets/javascripts/models/doc.js b/assets/javascripts/models/doc.js index 53d573cde2..707ace6328 100644 --- a/assets/javascripts/models/doc.js +++ b/assets/javascripts/models/doc.js @@ -43,11 +43,11 @@ app.models.Doc = class Doc extends app.Model { } fileUrl(path) { - return `${app.config.docs_origin}${this.fullPath(path)}?${this.mtime}`; + return `//${app.config.docs_origin}${this.fullPath(path)}?${this.mtime}`; } dbUrl() { - return `${app.config.docs_origin}/${this.slug}/${app.config.db_filename}?${this.mtime}`; + return `//${app.config.docs_origin}/${this.slug}/${app.config.db_filename}?${this.mtime}`; } indexUrl() { diff --git a/lib/app.rb b/lib/app.rb index b5a2324cec..55c0dda062 100644 --- a/lib/app.rb +++ b/lib/app.rb @@ -76,7 +76,7 @@ class App < Sinatra::Application configure :production do set :static, false - set :docs_origin, "//" + ENV.fetch("DEVDOCS_DOCS_ORIGIN", "documents.devdocs.io") + set :docs_origin, ENV.fetch("DEVDOCS_DOCS_ORIGIN", "documents.devdocs.io") set :csp, "default-src 'self' *; script-src 'self' 'nonce-devdocs' https://www.google-analytics.com https://secure.gaug.es https://*.jquery.com; font-src 'none'; style-src 'self' 'unsafe-inline' *; img-src 'self' * data:;" use Rack::ConditionalGet @@ -427,7 +427,7 @@ def modern_browser?(browser) redirect "/#{doc}#{type}#{rest[0...-1]}#{query_string_for_redirection}" elsif !request.path.end_with?(".html") && user_has_docs?(doc) && supports_js_redirection? redirect_via_js(request.path) - elsif File.exist?(File.join(settings.public_folder, "docs", request.path.gsub("..",""))) + elsif settings.docs_host == settings.docs_origin && File.exist?(File.join(settings.public_folder, "docs", request.path.gsub("..",""))) send_file File.join(settings.public_folder, "docs", request.path.gsub("..","")), status: status else response.headers['Content-Security-Policy'] = settings.csp if settings.csp diff --git a/views/index.erb b/views/index.erb index 5c268f7b25..d9ccc0515c 100644 --- a/views/index.erb +++ b/views/index.erb @@ -22,7 +22,7 @@ - + DevDocs API Documentation