{"id":16285088,"url":"https://github.com/parente/z2jh-aws","last_synced_at":"2025-09-09T01:31:02.535Z","repository":{"id":136637330,"uuid":"201824245","full_name":"parente/z2jh-aws","owner":"parente","description":"🥞 Zero-to-JupyterHub with Kubernetes using an opinionated tech stack","archived":false,"fork":false,"pushed_at":"2019-08-12T11:14:53.000Z","size":11,"stargazers_count":12,"open_issues_count":1,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-12-29T15:10:30.821Z","etag":null,"topics":["aws","cloudflare","helm","helmfile","jupyter","kubernetes","letsencrypt","terraform"],"latest_commit_sha":null,"homepage":"","language":"Makefile","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/parente.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-08-11T23:03:26.000Z","updated_at":"2022-11-11T19:43:27.000Z","dependencies_parsed_at":"2024-09-25T23:45:28.431Z","dependency_job_id":null,"html_url":"https://github.com/parente/z2jh-aws","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/parente%2Fz2jh-aws","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/parente%2Fz2jh-aws/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/parente%2Fz2jh-aws/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/parente%2Fz2jh-aws/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/parente","download_url":"https://codeload.github.com/parente/z2jh-aws/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":232374879,"owners_count":18513593,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws","cloudflare","helm","helmfile","jupyter","kubernetes","letsencrypt","terraform"],"created_at":"2024-10-10T19:22:11.287Z","updated_at":"2025-01-03T17:47:48.830Z","avatar_url":"https://github.com/parente.png","language":"Makefile","funding_links":[],"categories":[],"sub_categories":[],"readme":"## z2jh-aws\n\nA take on [Zero-to-JupyterHub with Kubernetes](https://zero-to-jupyterhub.readthedocs.io/en/latest/)\nusing a very specific tech stack, namely:\n\n- [Terraform](https://www.terraform.io/) for AWS infrastructure config management\n- [AWS Elastic Kubernetes Service](https://aws.amazon.com/eks/) (EKS) via the\n  [howdio EKS Terraform module](https://registry.terraform.io/modules/howdio/eks/aws/0.6.0)\n- [AWS Elastic Container Registry](https://aws.amazon.com/ecr/) (ECR) for storing custom JupyterHub\n  and user images\n- [Helm](https://helm.sh/) and [Helmfile](https://github.com/roboll/helmfile) for deploying\n  applications to Kubernetes including\n  [external-dns](https://github.com/kubernetes-incubator/external-dns),\n  [nginx-ingress](https://github.com/kubernetes/ingress-nginx),\n  [jetstack/cert-manager](https://github.com/jetstack/cert-manager), and\n  [jupyterhub](https://github.com/jupyterhub/helm-chart)\n- [Cloudflare](https://cloudflare.com) for DNS\n- [Let's Encrypt](https://letsencrypt.org/) for TLS certificates\n- [Homebrew](https://brew.sh/) for installing client tools on macOS\n- [Make](https://www.gnu.org/software/make/) for simplifying local commands\n\n## Before You Begin\n\nMake sure the tech stack above and all the complexity that comes with it are a good fit for your use\ncase before continuing. Here are some alternatives:\n\n- If you only need a Jupyter Notebook server for yourself, you do not need to set up JupyterHub. You\n  should instead follow the instructions to\n  [install](https://jupyter.readthedocs.io/en/latest/install.html) and\n  [run](https://jupyter.readthedocs.io/en/latest/running.html) a standalone Jupyter Notebook server.\n- If you need to run Jupyter Notebook servers for a small group of people and have no interest in\n  learning about Kubernetes, you will be better off following the guide for\n  [The Littlest JupyterHub](https://the-littlest-jupyterhub.readthedocs.io/en/latest/).\n- If you intend to use a Kubernetes provider other than AWS, you should follow the instructions in\n  the full [Zero-to-JupyterHub](https://zero-to-jupyterhub.readthedocs.io/en/latest/) guide.\n- If you are familiar with Kubernetes but have never configured JupyterHub on run on k8s before, you\n  should follow the instructions in the full\n  [Zero-to-JupyterHub](https://zero-to-jupyterhub.readthedocs.io/en/latest/) guide at least once\n  before using the highly-opinionated shortcuts enabled by this repository.\n\n## Prerequisites\n\n- macOS\n- Homebrew\n- A public domain name\n\n## Basic Usage\n\n1. Install tools used throughout the rest of the instructions using `brew`.\n\n   ```shell\n   make client-prereqs\n   ```\n\n1. Create an\n   [AWS IAM access key and secret](https://aws.amazon.com/premiumsupport/knowledge-center/create-access-key/)\n   for the account that will be used to provision AWS infrastructure.\n1. Configure a profile (e.g., `personal`) in `~/.aws/credentials` containing the IAM credentials and\n   desired region for your AWS infrastructure.\n\n   ```\n   [personal]\n   aws_access_key_id=YOUR_IAM_KEY_ID\n   aws_secret_access_key=YOUR_IAM_KEY_SECRET\n   region=us-east-1\n   ```\n\n1. Configure Elastic Kubernetes Service (EKS) and Elastic Container Registry (ECR) instances on AWS\n   using Terraform. **Fair warning: AWS will start charging you after you run this command.**\n\n   ```shell\n   export AWS_PROFILE=personal\n   make k8s-cluster\n   ```\n\n1. Sign up for a (free) [CloudFlare](https://cloudflare.com) account if you don't already have one.\n1. Add a site to your Cloudflare account matching your domain name (e.g., `parente.dev`).\n1. Login to your domain name registrar to configure your domain name to use the CloudFlare\n   nameservers (currently, `alec.ns.cloudflare.com` and `alice.ns.cloudflare.com`).\n1. Back on the CloudFlare website, click the Crypto icon for your new site and change the SSL\n   dropdown to Full.\n1. Also on the CloudFlare site, get your CloudFlare API token from My Profile \u0026rarr; API Tokens\n   \u0026rarr; Global API Key. p.\n1. Now at the console, apply configurations to Kubernetes for Helm tiller, nginx ingress, Let's\n   Encrypt certificate issuer, and CloudFlare DNS.\n\n   ```shell\n   export FQDN=parente.dev\n   export CLOUDFLARE_API_KEY=YOUR_CLOUDFLARE_API_KEY\n   export CLOUDFLARE_EMAIL=parente@gmail.com\n   make k8s-services\n   ```\n\n1. Deploy JupyterHub configured to use the `jupyter/minimal-notebook` Docker image from\n   [jupyter/docker-stacks](https://github.com/jupyter/docker-stacks) and\n   [FirstUseAuthenticator](https://github.com/jupyterhub/firstuseauthenticator).\n\n   ```shell\n   make jupyterhub\n   ```\n\n1. Visit `https://YOUR_DOMAIN` in your browser.\n1. Login with username `admin` and a strong password of your choosing.\n1. Click File \u0026rarr; Hub Control Panel \u0026rarr; Admin \u0026rarr; Add Users to populate a whitelist of\n   users allowed to login.\n\n## Customization / How do I ...\n\n### See what's configured in Kubernetes\n\n```shell\nmake show\n```\n\n### Use a different JupyterHub Docker image tag\n\nSee https://jupyterhub.github.io/helm-chart/ for available versions and\nhttps://github.com/jupyterhub/zero-to-jupyterhub-k8s/tree/master/images/hub for the contents of each\nimage. Substitute the version you want into the command below.\n\n```shell\nmake jupyterhub HUB_IMAGE_TAG=0.8.2\n```\n\n### Use a different Docker image as my user environment\n\nChoose any of the images maintained at or derived from https://github.com/jupyter/docker-stacks.\nProduce one of your own using https://github.com/jupyterhub/repo2docker. Then substitute the image\nname and tag in the command below.\n\n```\nmake jupyterhub USER_IMAGE=jupyter/datascience-notebook USER_IMAGE_TAG=2ce7c06a61a1\n```\n\n### Build private, custom JupyterHub and user Docker images\n\n1. Modify the `Dockerfile.hub` and `Dockerfile.user` files in this repository so that they define\n   the Docker images you want to use.\n2. Run the following commands to build the images and push them to the AWS ECR instances you\n   provisioned during setup. Specify whatever tag / version number you want to assign to the images\n   (default: `latest`).\n\n   ```shell\n   make hub-image HUB_IMAGE_TAG=1\n   make user-image USER_IMAGE_TAG=1\n   ```\n\n3. Run the following command to deploy JupyterHub with your custom images:\n\n   ```shell\n   make jupyterhub-custom HUB_IMAGE_TAG=1 USER_IMAGE_TAG=1\n   ```\n\n### Use a different method of authentication\n\nModify the `auth` section in `helmfile.yaml` based on the guidance in the\n[Authentication section of Zero to JupyterHub](https://zero-to-jupyterhub.readthedocs.io/en/latest/authentication.html).\n\n### Use a different DNS, Kubernetes, TLS, etc. provider\n\nRefer to the\n[Zero to JupyterHub with Kubernetes](https://zero-to-jupyterhub.readthedocs.io/en/latest/)\ndocumentation and share your own take on the general instructions in your own GitHub project.\n\n### Run these commands on a different operating system\n\nUse the approprate package manager for your platform to install all of the tools instead by\n`make client-prereqs`. If `make` is not any option for you, run the commands specified in the\n`Makefile` directly.\n\n### Run kubectl commands\n\n```shell\ncd z2jh-aws\nexport KUBECONFIG=./output/jupyterhub/kubeconfig-jupyterhub\nkubectl get pods\n```\n\n### Tear everything down\n\n```shell\nmake destroy\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fparente%2Fz2jh-aws","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fparente%2Fz2jh-aws","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fparente%2Fz2jh-aws/lists"}