# jupyternb-setup
Software responsible for setting up Jupyter Hub Container for a FABRIC user.
## Overview
This package installs a startup script on the JH Container and configures the container as below:
NOTE: All files/directories created inside `/home/fabric/work` persist across container restarts.
### Tokens: `.tokens.json`
Creates a token file using the CI LOGON Refresh Token environment variable. This file is then used by Fablib to get tokens from the Credential Manager. The file is only created if it does not exist.
```
{
"refresh_token": "<refresh_token>",
"created_at": "2022-12-01 21:34:56"
}
```
### Config Directory: `fabric_config`
- Creates the `fabric_config` directory at the location: `/home/fabric/work` if does not exist already.
```
$ ls -ltr fabric_config
total 20
-rw-------. 1 fabric users 650 Dec 1 21:48 fabric_rc
-rw-------. 1 fabric users 363 Dec 1 21:48 ssh_config
-rw-------. 1 fabric users 0 Dec 1 21:48 requirements.txt
-rw-------. 1 fabric users 68 Dec 1 21:48 fabric_config.json
-rw-------. 1 fabric users 2575 Dec 1 21:48 slice_key
-rw-r--r--. 1 fabric users 569 Dec 1 21:48 slice_key.pub
```
#### FABRIC Environment: `fabric_rc`
- Creates a `fabric_rc` file if it does not exist and sets the environment variables to the default values. User can overide te defaults by updating the `fabric_rc` file.
```
export FABRIC_CREDMGR_HOST=cm.fabric-testbed.net
export FABRIC_ORCHESTRATOR_HOST=orchestrator.fabric-testbed.net
export FABRIC_BASTION_HOST=bastion-1.fabric-testbed.net
#export FABRIC_PROJECT_ID=<Update Project Id>
#export FABRIC_BASTION_USERNAME=<Update User Name>
export FABRIC_BASTION_KEY_LOCATION=/home/fabric/work/fabric_config/fabric-bastion-key
export FABRIC_SLICE_PRIVATE_KEY_FILE=/home/fabric/work/fabric_config/slice_key
export FABRIC_SLICE_PUBLIC_KEY_FILE=/home/fabric/work/fabric_config/slice_key.pub
#export FABRIC_SLICE_PRIVATE_KEY_PASSPHRASE=<Update Passphrase>
export FABRIC_LOG_LEVEL=INFO
export FABRIC_LOG_FILE=/tmp/fablib/fablib.log
```
NOTE: Defaults are configurable via the environment variables passed to the container on JH install as below:
```
singleuser:
image:
name: fabrictestbed/jupyter-notebook
tag: 1.3.2
extraEnv:
FABRIC_CREDMGR_HOST: cm.fabric-testbed.net
FABRIC_ORCHESTRATOR_HOST: orchestrator.fabric-testbed.net
FABRIC_TOKEN_LOCATION: /home/fabric/.tokens.json
FABRIC_NOTEBOOK_LOCATION: /home/fabric/work
FABRIC_NOTEBOOK_TAGS: rel1.3.3
FABRIC_NOTEBOOK_REPO_URL: https://github.com/fabric-testbed/jupyter-examples/archive/refs/tags/
FABRIC_CONFIG_LOCATION: /home/fabric/work/fabric_config
FABRIC_BASTION_HOST: bastion-1.fabric-testbed.net
FABRIC_BASTION_PRIVATE_KEY_NAME: fabric-bastion-key
FABRIC_SLICE_PRIVATE_KEY_NAME: slice_key
FABRIC_SLICE_PUBLIC_KEY_NAME: slice_key.pub
```
#### Custom Python Packages: `requirements.txt`
- Creates an empty `requirements.txt` file if it does not exist. Any packages specified in this file are installed when the user container is spawned.
#### Jupyter Examples: `fabric_config.json`
- Creates `fabric_config.json` file if it does not exist with a default entry. This file is used to download the specific version of the Jupyter Hub Examples at the location specified. The default entry ensures release default version would be downloaded inside the container.
```
{
"examples": [
{"url": "default", "location": "/home/fabric/work/"}
]
}
```
Additional entries can be specified to download specific versions at a specified location such as below:
```
{"examples": [
{"url": "default", "location": "/home/fabric/work/"},
{"url": "https://github.com/fabric-testbed/jupyter-examples/archive/refs/tags/rel1.3.6.tar.gz", "location": "/home/fabric/"}
]}
```
For the below configuration, `jupyter-examples-rel1.3.6` would be downloaded at the location `/home/fabric`.
```
$ ls -ltr ~
total 4
drwxrwxr-x. 3 fabric users 147 Dec 1 21:28 jupyter-examples-rel1.3.6
drwxrwsrwx. 7 nobody users 4096 Dec 1 21:48 work
```
## Requirements
Python 3.9+
## Installation
Multiple installation options possible. For development the recommended method is to install from GitHub `main` branch:
```
$ mkvirtualenv jh-nb
$ workon jh-nb
$ pip install git+https://github.com/fabric-testbed/jupyternb-setup.git
```
For inclusion in tools, etc, use PyPi
```
$ mkvirtualenv jh-nb
$ workon jh-nb
$ pip install jupyternb-setup
```
NOTE: Any of the virtual environment tools ([venv], [virtualenv], or [virtualenvwrapper]) should work.
### Pre-requisites for the example above
Ensure that following are installed
```
virtualenv
virtualenvwrapper
```
Raw data
{
"_id": null,
"home_page": null,
"name": "jupyternb-setup",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "Fabric Jupyter Notebook Container Setup, Jupyter Hub, Jupyter Notebook",
"author": null,
"author_email": "Komal Thareja <kthare10@renci.org>",
"download_url": "https://files.pythonhosted.org/packages/a3/18/da88fe80210740b732ffb69b3a0e2b89069734295c12be5570c9a4e67be1/jupyternb-setup-1.3.7.tar.gz",
"platform": null,
"description": "# jupyternb-setup\nSoftware responsible for setting up Jupyter Hub Container for a FABRIC user.\n\n## Overview\nThis package installs a startup script on the JH Container and configures the container as below:\nNOTE: All files/directories created inside `/home/fabric/work` persist across container restarts.\n### Tokens: `.tokens.json`\nCreates a token file using the CI LOGON Refresh Token environment variable. This file is then used by Fablib to get tokens from the Credential Manager. The file is only created if it does not exist.\n``` \n{\n \"refresh_token\": \"<refresh_token>\", \n \"created_at\": \"2022-12-01 21:34:56\"\n}\n```\n### Config Directory: `fabric_config`\n- Creates the `fabric_config` directory at the location: `/home/fabric/work` if does not exist already.\n```\n$ ls -ltr fabric_config\ntotal 20\n-rw-------. 1 fabric users 650 Dec 1 21:48 fabric_rc\n-rw-------. 1 fabric users 363 Dec 1 21:48 ssh_config\n-rw-------. 1 fabric users 0 Dec 1 21:48 requirements.txt\n-rw-------. 1 fabric users 68 Dec 1 21:48 fabric_config.json\n-rw-------. 1 fabric users 2575 Dec 1 21:48 slice_key\n-rw-r--r--. 1 fabric users 569 Dec 1 21:48 slice_key.pub\n```\n#### FABRIC Environment: `fabric_rc`\n- Creates a `fabric_rc` file if it does not exist and sets the environment variables to the default values. User can overide te defaults by updating the `fabric_rc` file. \n```\nexport FABRIC_CREDMGR_HOST=cm.fabric-testbed.net\nexport FABRIC_ORCHESTRATOR_HOST=orchestrator.fabric-testbed.net\nexport FABRIC_BASTION_HOST=bastion-1.fabric-testbed.net\n#export FABRIC_PROJECT_ID=<Update Project Id>\n#export FABRIC_BASTION_USERNAME=<Update User Name>\nexport FABRIC_BASTION_KEY_LOCATION=/home/fabric/work/fabric_config/fabric-bastion-key\nexport FABRIC_SLICE_PRIVATE_KEY_FILE=/home/fabric/work/fabric_config/slice_key\nexport FABRIC_SLICE_PUBLIC_KEY_FILE=/home/fabric/work/fabric_config/slice_key.pub\n#export FABRIC_SLICE_PRIVATE_KEY_PASSPHRASE=<Update Passphrase>\nexport FABRIC_LOG_LEVEL=INFO\nexport FABRIC_LOG_FILE=/tmp/fablib/fablib.log\n```\nNOTE: Defaults are configurable via the environment variables passed to the container on JH install as below:\n```\nsingleuser:\n image:\n name: fabrictestbed/jupyter-notebook\n tag: 1.3.2\n extraEnv:\n FABRIC_CREDMGR_HOST: cm.fabric-testbed.net\n FABRIC_ORCHESTRATOR_HOST: orchestrator.fabric-testbed.net\n FABRIC_TOKEN_LOCATION: /home/fabric/.tokens.json\n FABRIC_NOTEBOOK_LOCATION: /home/fabric/work\n FABRIC_NOTEBOOK_TAGS: rel1.3.3\n FABRIC_NOTEBOOK_REPO_URL: https://github.com/fabric-testbed/jupyter-examples/archive/refs/tags/\n FABRIC_CONFIG_LOCATION: /home/fabric/work/fabric_config\n FABRIC_BASTION_HOST: bastion-1.fabric-testbed.net\n FABRIC_BASTION_PRIVATE_KEY_NAME: fabric-bastion-key\n FABRIC_SLICE_PRIVATE_KEY_NAME: slice_key\n FABRIC_SLICE_PUBLIC_KEY_NAME: slice_key.pub\n```\n#### Custom Python Packages: `requirements.txt`\n- Creates an empty `requirements.txt` file if it does not exist. Any packages specified in this file are installed when the user container is spawned.\n#### Jupyter Examples: `fabric_config.json`\n- Creates `fabric_config.json` file if it does not exist with a default entry. This file is used to download the specific version of the Jupyter Hub Examples at the location specified. The default entry ensures release default version would be downloaded inside the container.\n```\n{\n \"examples\": [\n {\"url\": \"default\", \"location\": \"/home/fabric/work/\"}\n ]\n}\n```\nAdditional entries can be specified to download specific versions at a specified location such as below:\n```\n{\"examples\": [\n {\"url\": \"default\", \"location\": \"/home/fabric/work/\"},\n {\"url\": \"https://github.com/fabric-testbed/jupyter-examples/archive/refs/tags/rel1.3.6.tar.gz\", \"location\": \"/home/fabric/\"}\n]}\n```\nFor the below configuration, `jupyter-examples-rel1.3.6` would be downloaded at the location `/home/fabric`.\n```\n$ ls -ltr ~\ntotal 4\ndrwxrwxr-x. 3 fabric users 147 Dec 1 21:28 jupyter-examples-rel1.3.6\ndrwxrwsrwx. 7 nobody users 4096 Dec 1 21:48 work\n```\n\n## Requirements\nPython 3.9+\n\n## Installation\nMultiple installation options possible. For development the recommended method is to install from GitHub `main` branch:\n```\n$ mkvirtualenv jh-nb\n$ workon jh-nb\n$ pip install git+https://github.com/fabric-testbed/jupyternb-setup.git\n```\nFor inclusion in tools, etc, use PyPi\n```\n$ mkvirtualenv jh-nb\n$ workon jh-nb\n$ pip install jupyternb-setup\n```\n\nNOTE: Any of the virtual environment tools ([venv], [virtualenv], or [virtualenvwrapper]) should work.\n\n### Pre-requisites for the example above\nEnsure that following are installed\n```\nvirtualenv\nvirtualenvwrapper\n```",
"bugtrack_url": null,
"license": null,
"summary": "Fabric Jupyter Notebook Container Setup",
"version": "1.3.7",
"project_urls": {
"Home": "https://fabric-testbed.net/",
"Sources": "https://github.com/fabric-testbed/jupyternb-setup"
},
"split_keywords": [
"fabric jupyter notebook container setup",
" jupyter hub",
" jupyter notebook"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "08d803aca4052e929f8d75ffd53f5481fbe2d9abd29c953a8e5346170f82166e",
"md5": "d39d6522ad1367c7dbc111241e6e1a1e",
"sha256": "7ccdbc4c1fd9918210814ced3f9d1059a8e4ce97c60931bf99f919d70ee22d01"
},
"downloads": -1,
"filename": "jupyternb_setup-1.3.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d39d6522ad1367c7dbc111241e6e1a1e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 8620,
"upload_time": "2024-06-27T18:01:53",
"upload_time_iso_8601": "2024-06-27T18:01:53.630297Z",
"url": "https://files.pythonhosted.org/packages/08/d8/03aca4052e929f8d75ffd53f5481fbe2d9abd29c953a8e5346170f82166e/jupyternb_setup-1.3.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "a318da88fe80210740b732ffb69b3a0e2b89069734295c12be5570c9a4e67be1",
"md5": "1bc3a0bdcfa72b73869a8096a152f9d8",
"sha256": "72eba6464be73207da1aad2a4d0b8838c00960ef0e2ddcac0937744a5902f868"
},
"downloads": -1,
"filename": "jupyternb-setup-1.3.7.tar.gz",
"has_sig": false,
"md5_digest": "1bc3a0bdcfa72b73869a8096a152f9d8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 7982,
"upload_time": "2024-06-27T18:01:54",
"upload_time_iso_8601": "2024-06-27T18:01:54.797853Z",
"url": "https://files.pythonhosted.org/packages/a3/18/da88fe80210740b732ffb69b3a0e2b89069734295c12be5570c9a4e67be1/jupyternb-setup-1.3.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-06-27 18:01:54",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "fabric-testbed",
"github_project": "jupyternb-setup",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "jupyternb-setup"
}
JSON
