{"id":19152520,"url":"https://github.com/gesiscss/persistent_binderhub","last_synced_at":"2025-05-07T05:45:28.808Z","repository":{"id":40313881,"uuid":"241634541","full_name":"gesiscss/persistent_binderhub","owner":"gesiscss","description":"A Helm chart repo to install persistent BinderHub ","archived":false,"fork":false,"pushed_at":"2022-12-13T20:20:08.000Z","size":1327,"stargazers_count":19,"open_issues_count":6,"forks_count":14,"subscribers_count":13,"default_branch":"master","last_synced_at":"2025-03-31T06:51:11.927Z","etag":null,"topics":["binder","binderhub","helm-chart","jupyterhub","kubernetes","persistent-storage"],"latest_commit_sha":null,"homepage":"https://gesiscss.github.io/persistent_binderhub/","language":"Python","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/gesiscss.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-02-19T13:55:24.000Z","updated_at":"2023-11-07T12:53:41.000Z","dependencies_parsed_at":"2023-01-28T14:47:25.592Z","dependency_job_id":null,"html_url":"https://github.com/gesiscss/persistent_binderhub","commit_stats":null,"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gesiscss%2Fpersistent_binderhub","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gesiscss%2Fpersistent_binderhub/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gesiscss%2Fpersistent_binderhub/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gesiscss%2Fpersistent_binderhub/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gesiscss","download_url":"https://codeload.github.com/gesiscss/persistent_binderhub/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249738800,"owners_count":21318504,"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":["binder","binderhub","helm-chart","jupyterhub","kubernetes","persistent-storage"],"created_at":"2024-11-09T08:18:12.164Z","updated_at":"2025-04-19T16:32:47.978Z","avatar_url":"https://github.com/gesiscss.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"**This repository is no longer actively maintained!**\n\nHowever, the development of this functionality continues in cooperation with 2i2c.org. For more information, see our blog post:\n\n👉  https://2i2c.org/blog/2022/gesis-2i2c-collaboration-update/\n\n\n# Persistent BinderHub\n\nThis is a Helm chart to install a persistent BinderHub.\nIt simply configures and extends [BinderHub chart](https://github.com/jupyterhub/binderhub) to add persistent storage,\nit doesn't define any new component.\nTherefore before using this chart it is required that you read through [BinderHub documentation](https://binderhub.readthedocs.io/en/latest/),\nyou know how to deploy a [standard BinderHub](http://mybinder.org/)\nand you are familiar with [enabling authentication](https://binderhub.readthedocs.io/en/latest/authentication.html) in BinderHub.\n\n- [Prerequisites](#prerequisites)\n  - [User storage](#user-storage)\n  - [Authentication](#authentication)\n- [Installing the chart](#installing-the-chart)\n  - [Known issues](#known-issues)\n- [Uninstalling the chart](#uninstalling-the-chart)\n- [Customization](#customization)\n  - [BinderHub customization](#binderhub-customization)\n  - [Default project](#default-project)\n  - [Projects limit per user](#projects-limit-per-user)\n  - [Repo providers](#repo-providers)\n  - [Spawner](#spawner)\n- [Local development](#local-development)\n- [Migrating from JupyterHub chart](#migrating-from-jupyterhub-chart)\n- [Limitations](#limitations)\n\n## Prerequisites\n\nFirst of all create a `config.yaml` file, everything explained here can go into that file\nand then it will be used for the installation.\nBefore the installation there are configurations required to be done for `User storage` and `Authentication`.\n\n### User storage\n\nTo be able to offer a persistent storage to users, in your kubernetes cluster you need to have a\n[storage class](https://kubernetes.io/docs/concepts/storage/storage-classes/) defined,\nwhich dynamically provisions persistent volumes. Please follow the\n[user storage documentation](https://zero-to-jupyterhub.readthedocs.io/en/latest/customizing/user-storage.html)\nof [JupyterHub chart](https://zero-to-jupyterhub.readthedocs.io/) for more information.\n\nNote that any configuration for JupyterHub chart goes under `binderhub.jupyterhub`\nin `config.yaml` that you created to install this chart. For example, if you want to specify the storage class,\nyou have to add the following into your `config.yaml`:\n\n```yaml\nbinderhub:\n  jupyterhub:\n    singleuser:\n      storage:\n        dynamic:\n          storageClass: \u003cstorageclass-name\u003e\n```\n\n### Authentication\n\nThis chart already includes some of the required changes for\n[enabling authentication](https://binderhub.readthedocs.io/en/latest/authentication.html#enabling-authentication).\nBut there are pieces that have to be manually configured. In your `config.yaml`:\n\n1. You have to set `oauth_client_id`:\n\n```bash\nbinderhub:\n  jupyterhub:\n    hub:\n      services:\n        binder:\n          # this is the default value\n          oauth_client_id: \"binder-oauth-client-test\"\n```\n\n2. You have to use config of your authenticator for `binderhub.jupyterhub.auth`.\n   For more information you can check the\n   [authentication guide](https://zero-to-jupyterhub.readthedocs.io/en/latest/administrator/authentication.html).\n\n```bash\nbinderhub:\n  jupyterhub:\n    hub:\n      config:\n        JupyterHub:\n          authenticator_class: dummy\n```\n\nNote that by default the authenticator is [DummyAuthenticator](https://github.com/jupyterhub/dummyauthenticator)\nand it is recommended to use it only for testing purposes.\n\n## Installing the chart\n\nFirst of all you can find the list of charts here:\nhttps://gesiscss.github.io/persistent_binderhub/\n\nThe installation consists of 2 steps. As a first step we install the chart,\nthen we will finalize the configuration of the Binder service\nand upgrade the chart to apply final changes in the config.\n\nTo install the chart with the release name `pbhub` into namespace `pbhub-ns`:\n\n```bash\n# add the persistent_binderhub helm chart repo\nhelm repo add persistent_binderhub https://gesiscss.github.io/persistent_binderhub/\n# update charts\nhelm repo update\n\n# you can change release name and namespace as you want\nRELEASENAME=pbhub\nNAMESPACE=pbhub-ns\nkubectl create namespace $NAMESPACE\nhelm upgrade $RELEASENAME persistent_binderhub/persistent_binderhub \\\n             --version=0.2.0-n919 \\\n             --install --namespace=$NAMESPACE \\\n             --debug \\\n             -f config.yaml\n```\n\nAfter the first step, run `kubectl get service proxy-public --namespace=$NAMESPACE`\nand note down the IP address under `EXTERNAL-IP`, which is the IP of the JupyterHub.\nThen run `kubectl get service binder --namespace=$NAMESPACE`\nand again note down the IP address under `EXTERNAL-IP`, which is the IP of the Binder service.\n\nWith the IP addresses you just acquired update your `config.yaml`:\n\n```bash\nbinderhub:\n  jupyterhub:\n    hub:\n      services:\n        binder:\n          # where binder runs\n          url: \"http://\u003cBinder_IP\u003e\"\n          # when url is set, binder can be reached through JupyterHub\n          oauth_redirect_uri: \"http://\u003cJupyterHub_IP\u003e/services/binder/oauth_callback\"\n```\n\nFinally upgrade the chart to apply this change:\n\n```bash\nhelm upgrade $RELEASENAME persistent_binderhub/persistent_binderhub \\\n             --version=0.2.0-n919 \\\n             --install --namespace=$NAMESPACE \\\n             --debug \\\n             -f config.yaml\n```\n\nWhen the installation is done,\nthe persistent BinderHub will be available at \"http://\u003cJupyterHub_IP\u003e\",\nand there (at JupyterHub home page) you will see a customized BinderHub UI for persistence,\nwhich is the place that users will interact with the system mostly.\nThe standard BinderHub will be available at \"http://\u003cJupyterHub_IP\u003e/services/binder\" as a service of JupyterHub.\n\n### Known issues\n\n1. If you don't know the url of the JupyterHub (`binderhub.config.BinderHub.hub_url`)\n   and it is not set during the first step of the installation,\n   you will get an error similar to\n   `Error: render error in \"persistent_binderhub/charts/binderhub/templates/deployment.yaml\": template: persistent_binderhub/charts/binderhub/templates/deployment.yaml:98:74: executing \"persistent_binderhub/charts/binderhub/templates/deployment.yaml\" at \u003c\"/\"\u003e: invalid value; expected string`  \n   To fix it, you can use a dummy value for the `hub_url`, e.g. \"http://127.0.0.1\",  \n   and after the first step when you have the correct url of the hub, you can replace it.  \n   GitHub issue: https://github.com/gesiscss/persistent_binderhub/issues/5  \n   Potential fix: https://github.com/jupyterhub/binderhub/pull/1139\n\n## Uninstalling the chart\n\n```bash\n# to delete the Helm release\nhelm delete $RELEASENAME --purge\n# to delete the Kubernetes namespace\nkubectl delete namespace $NAMESPACE\n```\n\n## Customization\n\nAs mentioned before, this chart extends the BinderHub chart in order to bring persistency in.\nTo do that this chart also uses `extraConfig` from JupyterHub and BinderHub charts. While using persistent BinderHub chart,\nyou should use another name for your `extraConfig`s,\nunless you want to overwrite defaults of this chart and you know what you are doing.\nHere is the list of `extraConfig`s used:\n\n- `binderhub.extraConfig`:\n\n  - `20-launcher`\n  - `10-repo-providers`\n\n- `binderhub.jupyterhub.hub.extraConfig`:\n  - `20-template-variables`\n  - `10-project-api`\n  - `00-binder`\n\nFor more information check [values.yaml](persistent_binderhub/values.yaml).\n\n### BinderHub customization\n\nAnything you want to customize in BinderHub chart you can refer to the\n[BinderHub documentation](https://binderhub.readthedocs.io/en/latest/).\nThe only thing you have to pay attention is that you put that configs under `binderhub` in your `config.yaml`.\nFor example, if you want to use another version of repo2docker to build repos, add following into your `config.yaml`:\n\n```yaml\nbinderhub:\n  config:\n    BinderHub:\n      build_image: quay.io/jupyterhub/repo2docker:2021.08.0-8.gf1d01b6\n```\n\nNote: `repo2docker:2021.08.0-8.gf1d01b6` is the repo2docker version used in this chart.\n\n### Default project\n\nA project is simply a binder-ready repository that you launch in a persistent BinderHub.\n\nDefault project is this repo itself by default\n(check [.binder folder](.binder), there is `intro_to_persistent_binderhub` notebook).\n\nAssuming that you have a binder-ready repo with the following information\n\n- repo url: `https://github.com/user_name/repo_name`\n- branch or tag or commit: `ref`\n\nyou can set it as default project by adding the following into your `config.yaml`:\n\n```yaml\nbinderhub:\n  jupyterhub:\n    custom:\n      default_project:\n        repo_url: \"https://github.com/user_name/repo_name\"\n        ref: \"ref\"\n```\n\nWarning: Default project must be a binder-ready repo, e.g. https://github.com/binder-examples/requirements.\n\n### Projects limit per user\n\nNumber of projects concurrently stored per user. By default it is 5.\nFor example, if you want to increase it to 10,\nadd the following into your `config.yaml`:\n\n```yaml\nbinderhub:\n  extraEnv:\n    - name: PROJECTS_LIMIT_PER_USER\n      value: \"10\" # change this value as you wish\n```\n\n\u003c!-- we shouldn't encourage people not to have no limit. --\u003e\n\u003c!-- If you want to have no projects limit, set `PROJECTS_LIMIT_PER_USER` to \"0\". --\u003e\n\n### Repo providers\n\nOnly the following repo providers are supported in this chart:\n\n- GitHubRepoProvider\n- GistRepoProvider\n- GitLabRepoProvider\n- GitRepoProvider\n\nOther providers (ZenodoProvider, FigshareProvider, HydroshareProvider, DataverseProvider) are currently not supported.\nIf you enable them, persistent BinderHub is not going to work as expected for these providers.\n\nFor example, if you want to only enable `GitHubRepoProvider` and `GistRepoProvider`,\nadd the following into your config.yaml:\n\n```yaml\nbinderhub:\n  extraConfig:\n    10-repo-providers: |\n      from binderhub.repoproviders import GitHubRepoProvider, GistRepoProvider\n      c.BinderHub.repo_providers = {\n          'gh': GitHubRepoProvider,\n          'gist': GistRepoProvider,\n      }\n```\n\n### Spawner\n\nThis chart uses the\n[PersistentBinderSpawner](https://github.com/gesiscss/persistent_binderhub/blob/master/persistent_binderhub/files/jupyterhub/persistent_bhub_config.py#L19).\nIf you want to customize it, you can subclass it in `extraConfig`. For example:\n\n```yaml\nbinderhub:\n  jupyterhub:\n    hub:\n      extraConfig:\n        00-binder: |\n          from persistent_bhub_config import PersistentBinderSpawner\n          MyPersistentBinderSpawner(PersistentBinderSpawner):\n            ...\n          c.JupyterHub.spawner_class = MyPersistentBinderSpawner\n```\n\n## Local development\n\nIn [local/minikube](local/minikube) folder you can find instructions and configuration file to install this chart in minikube.\n\n## Migrating from JupyterHub chart\n\nBe aware that this is not tested widely,\nbut it should be safe to migrate from [JupyterHub chart](https://zero-to-jupyterhub.readthedocs.io/) to this chart.\n\nHere are the differences compared to fresh installation of this chart:\n\n- after migration, existing users will have no default project in the beginning\n- files of existing users won't be copied to anywhere,\n  existing users can find them under `/projects` dir and\n  they should manage them manually via terminal\n\n## Limitations\n\n1. Binder pod (`binderhub.replicas`) must be 1, otherwise there are authentication errors\n   (https://github.com/jupyterhub/jupyterhub/issues/2841).\n\n---\n\nFunded by the German Research Foundation (DFG).\nFKZ/project number:\n[324867496](https://gepris.dfg.de/gepris/projekt/324867496?context=projekt\u0026task=showDetail\u0026id=324867496\u0026).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgesiscss%2Fpersistent_binderhub","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgesiscss%2Fpersistent_binderhub","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgesiscss%2Fpersistent_binderhub/lists"}