From 4850dd67d7393a31c6080ec93a0167c54f62aa8d Mon Sep 17 00:00:00 2001 From: Keith Fung Date: Mon, 21 Sep 2020 10:24:44 -0400 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20Improve=20Documentation=20(#84)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * 📝. Add Docker Documentation * Link DockerHub images in the README badges Co-authored-by: Ryan Korsak --- README.md | 35 +++++++++++++++++++++++++++++++---- docs/index.md | 33 ++++++++++++++++++++++++++++++--- mkdocs.yml | 10 +++++----- 3 files changed, 66 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index f45a0af..d1fabf0 100644 --- a/README.md +++ b/README.md @@ -2,9 +2,11 @@ # 🗳️ ElectionGuard Web API -![docker version](https://img.shields.io/docker/v/electionguard/electionguard-web-api) ![docker pulls](https://img.shields.io/docker/pulls/electionguard/electionguard-web-api) [![Language grade: Python](https://img.shields.io/lgtm/grade/python/g/microsoft/electionguard-web-api.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/microsoft/electionguard-web-api/context:python) [![Total alerts](https://img.shields.io/lgtm/alerts/g/microsoft/electionguard-web-api.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/microsoft/electionguard-web-api/alerts/) [![Documentation Status](https://readthedocs.org/projects/electionguard-web-api/badge/?version=latest)](https://electionguard-web-api.readthedocs.io) [![license](https://img.shields.io/github/license/microsoft/electionguard-web-api)](LICENSE) +[![docker version](https://img.shields.io/docker/v/electionguard/electionguard-web-api)](https://hub.docker.com/r/electionguard/electionguard-web-api) [![docker pulls](https://img.shields.io/docker/pulls/electionguard/electionguard-web-api)](https://hub.docker.com/r/electionguard/electionguard-web-api) [![Language grade: Python](https://img.shields.io/lgtm/grade/python/g/microsoft/electionguard-web-api.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/microsoft/electionguard-web-api/context:python) [![Total alerts](https://img.shields.io/lgtm/alerts/g/microsoft/electionguard-web-api.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/microsoft/electionguard-web-api/alerts/) [![Documentation Status](https://readthedocs.org/projects/electionguard-web-api/badge/?version=latest)](https://electionguard-web-api.readthedocs.io) [![license](https://img.shields.io/github/license/microsoft/electionguard-web-api)](LICENSE) -This is a python API that utilizes [`electionguard-python`](https://github.com/microsoft/electionguard-python) to perform ballot encryption, casting, spoiling, and tallying. This API is implemented using [FastAPI](https://fastapi.tiangolo.com/#interactive-api-docs). +This is a python API that provides a **thin**, **stateless** wrapper around the [`electionguard-python`](https://github.com/microsoft/electionguard-python) library to perform ballot encryption, casting, spoiling, and tallying. This API is implemented using [FastAPI](https://fastapi.tiangolo.com/#interactive-api-docs). + +If you aren't familiar with ElectionGuard and its concepts, [take a stroll through the official documentation](https://microsoft.github.io/electionguard-python/) first! ## 👯‍♀️ Two APIs in One @@ -23,11 +25,36 @@ In practice, you will likely need to run at least one instance of each mode. We - 🐳🐍 [GNU Make](https://www.gnu.org/software/make/manual/make.html) is used to simplify the commands and GitHub Actions. This approach is recommended to simplify the command line experience. This is built in for MacOS and Linux. For Windows, setup is simpler with [Chocolatey](https://chocolatey.org/install) and installing the provided [make package](https://chocolatey.org/packages/make). The other Windows option is [manually installing make](http://gnuwin32.sourceforge.net/packages/make.htm). - 🐍 [Python 3.8](https://www.python.org/downloads/) is **required** to develop this API. If developer uses multiple versions of python, [pyenv](https://github.com/pyenv/pyenv) is suggested to assist version management. -- 🐍 [poetry](https://python-poetry.org/docs/) is used to configure the python environment. This can be installed via pip or pipx. ## 🐳 Running with Docker -If you run Docker and want to get started quickly, we provide a Dockerfile and docker-compose.yml. +### The official Docker image + +We host a Docker image on both [Github Packages](https://github.com/microsoft/electionguard-web-api/packages/397920) and [DockerHub](https://hub.docker.com/r/electionguard/electionguard-web-api). + +**Note:** _GitHub Packages requires authentication to retrieve the package. This requires a GitHub Access Token and using `docker login`. [Follow GitHub instructions](https://docs.github.com/en/packages/using-github-packages-with-your-projects-ecosystem/configuring-docker-for-use-with-github-packages#authenticating-with-a-personal-access-token)._ + +```bash +# Pull the image from DockerHub +docker pull docker.pkg.github.com/microsoft/electionguard-web-api/electionguard-web-api:main + +# Start a container for the API in mediator mode, exposed on port 80 of the host machine +docker run -d -p 80:8000 --env API_MODE=mediator docker.pkg.github.com/microsoft/electionguard-web-api/electionguard-web-api:main +``` + +OR + +```bash +# Pull the image from DockerHub +docker pull electionguard/electionguard-web-api:latest + +# Start a container for the API in mediator mode, exposed on port 80 of the host machine +docker run -d -p 80:8000 --env API_MODE=mediator electionguard/electionguard-web-api:latest +``` + +### Developing locally with Docker + +If you run Docker and want to run the code locally without Python dependencies, we provide a Dockerfile and docker-compose.yml. Run both APIs at the same time: diff --git a/docs/index.md b/docs/index.md index 2a30a26..a984250 100644 --- a/docs/index.md +++ b/docs/index.md @@ -4,7 +4,9 @@ ![docker version](https://img.shields.io/docker/v/electionguard/electionguard-web-api) ![docker pulls](https://img.shields.io/docker/pulls/electionguard/electionguard-web-api) [![Language grade: Python](https://img.shields.io/lgtm/grade/python/g/microsoft/electionguard-web-api.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/microsoft/electionguard-web-api/context:python) [![Total alerts](https://img.shields.io/lgtm/alerts/g/microsoft/electionguard-web-api.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/microsoft/electionguard-web-api/alerts/) [![Documentation Status](https://readthedocs.org/projects/electionguard-web-api/badge/?version=latest)](https://electionguard-web-api.readthedocs.io) [![license](https://img.shields.io/github/license/microsoft/electionguard-web-api)](LICENSE) -This is a python API that utilizes [`electionguard-python`](https://github.com/microsoft/electionguard-python) to perform ballot encryption, casting, spoiling, and tallying. This API is implemented using [FastAPI](https://fastapi.tiangolo.com/#interactive-api-docs). +This is a python API that provides a **thin**, **stateless** wrapper around the [`electionguard-python`](https://github.com/microsoft/electionguard-python) library to perform ballot encryption, casting, spoiling, and tallying. This API is implemented using [FastAPI](https://fastapi.tiangolo.com/#interactive-api-docs). + +If you aren't familiar with ElectionGuard and its concepts, [take a stroll through the official documentation](https://microsoft.github.io/electionguard-python/) first! ## 👯‍♀️ Two APIs in One @@ -23,11 +25,36 @@ In practice, you will likely need to run at least one instance of each mode. We - 🐳🐍 [GNU Make](https://www.gnu.org/software/make/manual/make.html) is used to simplify the commands and GitHub Actions. This approach is recommended to simplify the command line experience. This is built in for MacOS and Linux. For Windows, setup is simpler with [Chocolatey](https://chocolatey.org/install) and installing the provided [make package](https://chocolatey.org/packages/make). The other Windows option is [manually installing make](http://gnuwin32.sourceforge.net/packages/make.htm). - 🐍 [Python 3.8](https://www.python.org/downloads/) is **required** to develop this API. If developer uses multiple versions of python, [pyenv](https://github.com/pyenv/pyenv) is suggested to assist version management. -- 🐍 [poetry](https://python-poetry.org/docs/) is used to configure the python environment. This can be installed via pip or pipx. ## 🐳 Running with Docker -If you run Docker and want to get started quickly, we provide a Dockerfile and docker-compose.yml. +### The official Docker image + +We host a Docker image on both [Github Packages](https://github.com/microsoft/electionguard-web-api/packages/397920) and [DockerHub](https://hub.docker.com/r/electionguard/electionguard-web-api). + +**Note:** _GitHub Packages requires authentication to retrieve the package. This requires a GitHub Access Token and using `docker login`. [Follow GitHub instructions](https://docs.github.com/en/packages/using-github-packages-with-your-projects-ecosystem/configuring-docker-for-use-with-github-packages#authenticating-with-a-personal-access-token)._ + +```bash +# Pull the image from DockerHub +docker pull docker.pkg.github.com/microsoft/electionguard-web-api/electionguard-web-api:main + +# Start a container for the API in mediator mode, exposed on port 80 of the host machine +docker run -d -p 80:8000 --env API_MODE=mediator docker.pkg.github.com/microsoft/electionguard-web-api/electionguard-web-api:main +``` + +OR + +```bash +# Pull the image from DockerHub +docker pull electionguard/electionguard-web-api:latest + +# Start a container for the API in mediator mode, exposed on port 80 of the host machine +docker run -d -p 80:8000 --env API_MODE=mediator electionguard/electionguard-web-api:latest +``` + +### Developing locally with Docker + +If you run Docker and want to run the code locally without Python dependencies, we provide a Dockerfile and docker-compose.yml. Run both APIs at the same time: diff --git a/mkdocs.yml b/mkdocs.yml index 4f65cf4..ac6cdf6 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,12 +1,12 @@ site_name: ElectionGuard Web Api # site_description: site_author: Microsoft -# google_analytics: +# google_analytics: # remote_branch: for gh-deploy to GithubPages # remote_name: for gh-deploy to Github Pages -copyright: '© Microsoft 2020' -docs_dir: 'docs' +copyright: "© Microsoft 2020" +docs_dir: "docs" repo_url: https://github.com/microsoft/electionguard-web-api/ nav: - - Home: index.md -theme: readthedocs \ No newline at end of file + - Home: index.md +theme: readthedocs