How To: Create a private documentation website with GitHub OAuth 2.0 authorization

Use case scenario

You have your documentation sources hosted on your private repository, which belongs to your GitHub organization. What you would like to have is a hosted website that allows documentation surfing only to members of your organization, maybe hosted on your private server.

Solution: Docker containers

If your website hosting service supports Docker images and container hosting, thanks to OAuth2 Proxy this can be achieved with a simple, maybe not so simple, single Dockerfile:

FROM deloo/markdown-docs AS builder

COPY . /home/src # Copies documentation files
ENV WORKSPACE=/home/src
ENV PRIMARY_COLOR=indigo
ENV SECONDARY_COLOR=indigo
ENV ICON=library

# Variables for GitHub edit links
ARG GITHUB_SERVER_URL
ENV GITHUB_SERVER_URL=${GITHUB_SERVER_URL}
ARG GITHUB_REPOSITORY
ENV GITHUB_REPOSITORY=${GITHUB_REPOSITORY}
ARG GITHUB_REF
ENV GITHUB_REF=${GITHUB_REF}

RUN makedocs "." "dst"

FROM quay.io/oauth2-proxy/oauth2-proxy

ENV OAUTH2_PROXY_AUTH_LOGGING=false
ENV OAUTH2_PROXY_COOKIE_NAME=__SELECT_YOUR_COOKIE_NAME__
ENV OAUTH2_PROXY_EMAIL_DOMAINS=*
ENV OAUTH2_PROXY_GITHUB_ORG=__YOUR_ORGANIZATION_GITHUB_NAME__
ENV OAUTH2_PROXY_PROVIDER=github
ENV OAUTH2_PROXY_REVERSE_PROXY=true
ENV OAUTH2_PROXY_UPSTREAMS=file:///var/www/static/#/
ENV OAUTH2_PROXY_HTTP_ADDRESS=:8080
ENV OAUTH2_PROXY_HTTPS_ADDRESS=:443
# Work in progress https://oauth2-proxy.github.io/oauth2-proxy/docs/configuration/overview

COPY --from=builder /home/src/dst /var/www/static/

This configuration will require users to login with their GitHub account to check their organization membership, through the safe and secure OAuth 2.0 protocol. Enjoy!

Ps. In order to pass the github variables you need to run docker build with --build-arg GITHUB_SERVER_URL --build-arg GITHUB_REPOSITORY --build-arg GITHUB_REF inside a GitHub Actions CI or else you will need to artificially set them.

Pps. Tested with Azure Webapp service.