From 255207f7a6cd411ffd126339793efdaefa916ac4 Mon Sep 17 00:00:00 2001 From: Chaitanya Rahalkar Date: Fri, 13 Dec 2024 23:54:12 -0600 Subject: [PATCH 1/7] feat: add the GitHub action to create a Docker image and push to Docker's registry --- .github/workflows/docker-build.yml | 57 ++++++++++++++++++++++++++++++ 1 file changed, 57 insertions(+) create mode 100644 .github/workflows/docker-build.yml diff --git a/.github/workflows/docker-build.yml b/.github/workflows/docker-build.yml new file mode 100644 index 00000000..425c679e --- /dev/null +++ b/.github/workflows/docker-build.yml @@ -0,0 +1,57 @@ +name: Build and Push Docker Images + +on: + schedule: + - cron: '0 0 1 * *' # Run monthly on the 1st + workflow_dispatch: # Allow manual triggers + +env: + REGISTRY: ghcr.io + IMAGE_NAME: ${{ github.repository }} + +jobs: + build-and-push: + runs-on: ubuntu-latest + permissions: + contents: read + packages: write + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Log in to the Container registry + uses: docker/login-action@v3 + with: + registry: ${{ env.REGISTRY }} + username: ${{ github.actor }} + password: ${{ secrets.GITHUB_TOKEN }} + + - name: Extract metadata for Docker + id: meta + uses: docker/metadata-action@v5 + with: + images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }} + tags: | + type=raw,value=latest + type=raw,value={{date 'YYYYMMDD'}} + + - name: Build and push regular image + uses: docker/build-push-action@v5 + with: + context: . + file: ./Dockerfile + push: true + tags: ${{ steps.meta.outputs.tags }} + labels: ${{ steps.meta.outputs.labels }} + + - name: Build and push Alpine image + uses: docker/build-push-action@v5 + with: + context: . + file: ./Dockerfile-alpine + push: true + tags: | + ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:alpine + ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:alpine-{{date 'YYYYMMDD'}} + labels: ${{ steps.meta.outputs.labels }} \ No newline at end of file From f09db5ef5e858f3c54c0c8dde1a9aecf7046dde0 Mon Sep 17 00:00:00 2001 From: Chaitanya Rahalkar Date: Sat, 14 Dec 2024 13:24:24 -0600 Subject: [PATCH 2/7] Update docker-build.yml --- .github/workflows/docker-build.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/docker-build.yml b/.github/workflows/docker-build.yml index 425c679e..f2dc8669 100644 --- a/.github/workflows/docker-build.yml +++ b/.github/workflows/docker-build.yml @@ -53,5 +53,5 @@ jobs: push: true tags: | ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:alpine - ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:alpine-{{date 'YYYYMMDD'}} - labels: ${{ steps.meta.outputs.labels }} \ No newline at end of file + ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:alpine-${TAG_DATE} + labels: ${{ steps.meta.outputs.labels }} From 08b80c35be26b8815d310e9f3056d6633eef54a6 Mon Sep 17 00:00:00 2001 From: Chaitanya Rahalkar Date: Sat, 14 Dec 2024 14:23:08 -0600 Subject: [PATCH 3/7] Update docker-build.yml --- .github/workflows/docker-build.yml | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/.github/workflows/docker-build.yml b/.github/workflows/docker-build.yml index f2dc8669..6b8dad08 100644 --- a/.github/workflows/docker-build.yml +++ b/.github/workflows/docker-build.yml @@ -1,24 +1,25 @@ name: Build and Push Docker Images - on: schedule: - - cron: '0 0 1 * *' # Run monthly on the 1st + - cron: '0 0 1 *'* # Run monthly on the 1st workflow_dispatch: # Allow manual triggers - env: REGISTRY: ghcr.io IMAGE_NAME: ${{ github.repository }} - + TAG_DATE: ${{ format('{0}{1}{2}', github.event.repository.pushed_at.substring(0,4), github.event.repository.pushed_at.substring(5,7), github.event.repository.pushed_at.substring(8,10)) }} jobs: build-and-push: runs-on: ubuntu-latest permissions: contents: read packages: write - steps: - name: Checkout repository uses: actions/checkout@v4 + + - name: Set current date + id: date + run: echo "DATE=$(date +'%Y%m%d')" >> $GITHUB_ENV - name: Log in to the Container registry uses: docker/login-action@v3 @@ -34,7 +35,7 @@ jobs: images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }} tags: | type=raw,value=latest - type=raw,value={{date 'YYYYMMDD'}} + type=raw,value=${{ env.DATE }} - name: Build and push regular image uses: docker/build-push-action@v5 @@ -53,5 +54,5 @@ jobs: push: true tags: | ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:alpine - ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:alpine-${TAG_DATE} - labels: ${{ steps.meta.outputs.labels }} + ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:alpine-${{ env.DATE }} + labels: ${{ steps.meta.outputs.labels }} From 63effa3ce4f499b755d9dd9ce21ab5d21fe45b43 Mon Sep 17 00:00:00 2001 From: Chaitanya Rahalkar Date: Sat, 14 Dec 2024 14:25:06 -0600 Subject: [PATCH 4/7] Update docker-build.yml --- .github/workflows/docker-build.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/docker-build.yml b/.github/workflows/docker-build.yml index 6b8dad08..d548e667 100644 --- a/.github/workflows/docker-build.yml +++ b/.github/workflows/docker-build.yml @@ -1,8 +1,8 @@ name: Build and Push Docker Images on: schedule: - - cron: '0 0 1 *'* # Run monthly on the 1st - workflow_dispatch: # Allow manual triggers + - cron: '0 0 1 * *' # Run monthly on the 1st + workflow_dispatch: env: REGISTRY: ghcr.io IMAGE_NAME: ${{ github.repository }} From 58085bec3f39235409d0d4fe8fcea7455a4271d3 Mon Sep 17 00:00:00 2001 From: Chaitanya Rahalkar Date: Sat, 14 Dec 2024 14:26:05 -0600 Subject: [PATCH 5/7] Update docker-build.yml --- .github/workflows/docker-build.yml | 11 +++-------- 1 file changed, 3 insertions(+), 8 deletions(-) diff --git a/.github/workflows/docker-build.yml b/.github/workflows/docker-build.yml index d548e667..611a50cf 100644 --- a/.github/workflows/docker-build.yml +++ b/.github/workflows/docker-build.yml @@ -2,11 +2,10 @@ name: Build and Push Docker Images on: schedule: - cron: '0 0 1 * *' # Run monthly on the 1st - workflow_dispatch: + workflow_dispatch: # Allow manual triggers env: REGISTRY: ghcr.io IMAGE_NAME: ${{ github.repository }} - TAG_DATE: ${{ format('{0}{1}{2}', github.event.repository.pushed_at.substring(0,4), github.event.repository.pushed_at.substring(5,7), github.event.repository.pushed_at.substring(8,10)) }} jobs: build-and-push: runs-on: ubuntu-latest @@ -16,10 +15,6 @@ jobs: steps: - name: Checkout repository uses: actions/checkout@v4 - - - name: Set current date - id: date - run: echo "DATE=$(date +'%Y%m%d')" >> $GITHUB_ENV - name: Log in to the Container registry uses: docker/login-action@v3 @@ -35,7 +30,7 @@ jobs: images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }} tags: | type=raw,value=latest - type=raw,value=${{ env.DATE }} + type=raw,value={{date 'YYYYMMDD'}} - name: Build and push regular image uses: docker/build-push-action@v5 @@ -54,5 +49,5 @@ jobs: push: true tags: | ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:alpine - ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:alpine-${{ env.DATE }} + ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:alpine-{{date 'YYYYMMDD'}} labels: ${{ steps.meta.outputs.labels }} From 018747014834ad099b1c093295ff1d7c09325dc5 Mon Sep 17 00:00:00 2001 From: Chaitanya Rahalkar Date: Sat, 14 Dec 2024 14:52:05 -0600 Subject: [PATCH 6/7] Update docker-build.yml --- .github/workflows/docker-build.yml | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/.github/workflows/docker-build.yml b/.github/workflows/docker-build.yml index 611a50cf..b917f7de 100644 --- a/.github/workflows/docker-build.yml +++ b/.github/workflows/docker-build.yml @@ -32,6 +32,15 @@ jobs: type=raw,value=latest type=raw,value={{date 'YYYYMMDD'}} + - name: Extract metadata for Alpine + id: meta-alpine + uses: docker/metadata-action@v5 + with: + images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }} + tags: | + type=raw,value=alpine + type=raw,prefix=alpine-,value={{date 'YYYYMMDD'}} + - name: Build and push regular image uses: docker/build-push-action@v5 with: @@ -47,7 +56,5 @@ jobs: context: . file: ./Dockerfile-alpine push: true - tags: | - ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:alpine - ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:alpine-{{date 'YYYYMMDD'}} - labels: ${{ steps.meta.outputs.labels }} + tags: ${{ steps.meta-alpine.outputs.tags }} + labels: ${{ steps.meta-alpine.outputs.labels }} From 89334645fab186f1dcdb0be591453302a4a5322a Mon Sep 17 00:00:00 2001 From: Chaitanya Rahalkar Date: Mon, 16 Dec 2024 18:15:52 -0600 Subject: [PATCH 7/7] update README with instructions for the GH action --- .github/workflows/docker-build.yml | 32 +++++++++++++-------------- README.md | 35 ++++++++++++++++++++---------- 2 files changed, 40 insertions(+), 27 deletions(-) diff --git a/.github/workflows/docker-build.yml b/.github/workflows/docker-build.yml index 425c679e..bea7e87f 100644 --- a/.github/workflows/docker-build.yml +++ b/.github/workflows/docker-build.yml @@ -15,10 +15,21 @@ jobs: permissions: contents: read packages: write + strategy: + matrix: + variant: + - name: regular + file: Dockerfile + suffix: '' + - name: alpine + file: Dockerfile-alpine + suffix: '-alpine' steps: - name: Checkout repository uses: actions/checkout@v4 + with: + persist-credentials: false - name: Log in to the Container registry uses: docker/login-action@v3 @@ -33,25 +44,14 @@ jobs: with: images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }} tags: | - type=raw,value=latest - type=raw,value={{date 'YYYYMMDD'}} + type=raw,value=latest${{ matrix.variant.suffix }} + type=raw,value={{date 'YYYYMMDD'}}${{ matrix.variant.suffix }} - - name: Build and push regular image + - name: Build and push image uses: docker/build-push-action@v5 with: context: . - file: ./Dockerfile + file: ./${{ matrix.variant.file }} push: true tags: ${{ steps.meta.outputs.tags }} - labels: ${{ steps.meta.outputs.labels }} - - - name: Build and push Alpine image - uses: docker/build-push-action@v5 - with: - context: . - file: ./Dockerfile-alpine - push: true - tags: | - ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:alpine - ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:alpine-{{date 'YYYYMMDD'}} - labels: ${{ steps.meta.outputs.labels }} \ No newline at end of file + labels: ${{ steps.meta.outputs.labels }} \ No newline at end of file diff --git a/README.md b/README.md index 54c94761..97df20a1 100644 --- a/README.md +++ b/README.md @@ -20,6 +20,30 @@ Keep track of development news: Unless you wish to contribute to the project, we recommend using the hosted version at [devdocs.io](https://devdocs.io). It's up-to-date and works offline out-of-the-box. +### Using Docker (Recommended) + +The easiest way to run DevDocs locally is using Docker: + +```sh +docker run --name devdocs -d -p 9292:9292 ghcr.io/freecodcamp/devdocs:latest +``` + +This will start DevDocs at [localhost:9292](http://localhost:9292). We provide both regular and Alpine-based images: +- `ghcr.io/freecodcamp/devdocs:latest` - Standard image +- `ghcr.io/freecodcamp/devdocs:latest-alpine` - Alpine-based (smaller size) + +Images are automatically built and updated monthly with the latest documentation. + +Alternatively, you can build the image yourself: + +```sh +git clone https://github.com/freeCodeCamp/devdocs.git && cd devdocs +docker build -t devdocs . +docker run --name devdocs -d -p 9292:9292 devdocs +``` + +### Manual Installation + DevDocs is made of two pieces: a Ruby scraper that generates the documentation and metadata, and a JavaScript app powered by a small Sinatra app. DevDocs requires Ruby 3.3.0 (defined in [`Gemfile`](./Gemfile)), libcurl, and a JavaScript runtime supported by [ExecJS](https://github.com/rails/execjs#readme) (included in OS X and Windows; [Node.js](https://nodejs.org/en/) on Linux). Once you have these installed, run the following commands: @@ -38,17 +62,6 @@ 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: - -```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 -``` - ## Vision DevDocs aims to make reading and searching reference documentation fast, easy and enjoyable.