diff --git a/about/infrastructure.md b/about/infrastructure.md index 26c92e4..24780c4 100644 --- a/about/infrastructure.md +++ b/about/infrastructure.md @@ -84,6 +84,7 @@ Each 2i2c Hub has **hub name** (denoted by ``) and a **community name* It is also possible to provide your own URL that points to a 2i2c Hub. -## How could I deploy my own 2i2c Hub? - -Check out [](../admin/migrate.md) for information about migrating off of a 2i2c Hub, including deploying your own hub. +% TODO: add back in once #54 is merged +% ## How could I deploy my own 2i2c Hub? +% +% Check out [](../admin/migrate.md) for information about migrating off of a 2i2c Hub, including deploying your own hub. diff --git a/about/overview.md b/about/overview.md index 2af2ce5..a2768e4 100644 --- a/about/overview.md +++ b/about/overview.md @@ -37,7 +37,7 @@ It does this in collaboration with leaders from the community for a particular h :::{seealso} - **Roles needed to run a hub**: see {doc}`tc:sre` -- **Support options**: see [](../admin/support.md). +- **Support options**: see [](../admin/howto/support.md). ::: ## Funding open source @@ -49,7 +49,10 @@ We see this as an opportunity to solve two problems with one stream of funding: ## Moving off of a 2i2c Hub? -2i2c Hubs are designed to use entirely open-source tools that work in other contexts. You can take your workflows elsewhere if you wish, and you can even deploy your own JupyterHub that recreates the same cloud-based experience. For more information, see [](migration-guide). +2i2c Hubs are designed to use entirely open-source tools that work in other contexts. You can take your workflows elsewhere if you wish, and you can even deploy your own JupyterHub that recreates the same cloud-based experience. + +% TODO: add back in once #54 is merged. +% For more information, see [](migration-guide). ### Wait, you really want it to be easy for people to _leave_ 2i2c Hubs? diff --git a/admin/configuration/culling.md b/admin/configuration/culling.md new file mode 100644 index 0000000..9511980 --- /dev/null +++ b/admin/configuration/culling.md @@ -0,0 +1,13 @@ +# User server culling + +To ensure efficient resource usage, user servers without interactive usage for a +period of time (default `1h`) are automatically stopped (via +[jupyterhub-idle-culler](https://github.com/jupyterhub/jupyterhub-idle-culler)). +This means your notebook server might be stopped for inactivity even if you have +a long running process in the notebook. This timeout can be configured. + +% TODO: Add link to SRE guide on how to configure this, once it exists + +Culling has the same effect as [stopping a user's server](user-server/stopping). + +There is currently no maximum time limit for a user's notebook. diff --git a/admin/configuration/login.md b/admin/configuration/login.md new file mode 100644 index 0000000..259f23c --- /dev/null +++ b/admin/configuration/login.md @@ -0,0 +1,39 @@ +# User authentication & authorization + +**Authentication** allows your users to prove who their are. +**Authorization** gives users certain permissions depending on their identity (such as "access to your hub", or "administrative privileges"). + +(admin/configuration/authentication)= +## Authentication + +Users can prove who they are by logging in via an *authentication provider*. Currently, the following providers are supported: + +1. *Google*. This includes public `@gmail.com` accounts, as well as [Google Workspace](https://workspace.google.com/) accounts set up for your workspace or university. If you use the GMail interface to access your work / university email, it can be used here. + +2. [*GitHub*](https://github.com/). Extremely popular community of people creating, publishing and collaborating on code. Accounts are free, and many people already have them especially since the target community for most hubs are people who also write some kind of code. + +3. [*ORCID*](https://orcid.org/). Everyone who has published a paper has one of these, and anyone else can easily sign up. Almost exclusively used by researchers. + +4. ``. We may be able to support other authentication providers, depending on your specific needs and the provider's complexity. Please reach out to us if none of these 3 work. + +We will ask you what provider you want when we set up the hub. We can change the provider after the fact, but only if absolutely necessary. + +## Authorization + +Not everyone who can authenticate is granted access to the hub - that would mean +everyone with a `@gmail.com` account can log in if you use Google as your +authentication provider! Instead, we support multiple ways for hub admins to +specify which users are *authorized* to be on the hub. + +Authorizing regular users +: Currently, there are only two supported methods for authorizing regular users: + + 1. [Manually add users](../howto/manage-users.md) via the admin panel in JupyterHub + 2. (Google only) Allow all users who are logged in via a particular domain - so + you can allow access to anyone who is part of your organization or + educational institution. + +Authorizing admin users +: Admin users are authorized [in a hub's YAML config](https://github.com/2i2c-org/pilot-hubs/blob/master/hubs.yaml), with support from 2i2c staff. + +% TODO: Link to SRE docs on how to do this once we have it diff --git a/admin/content.md b/admin/content.md deleted file mode 100644 index ab70def..0000000 --- a/admin/content.md +++ /dev/null @@ -1,37 +0,0 @@ -# Create content for your Hub - -## Write public books that connect to a 2i2c Hub - -You can create public content that is designed to have connections with your 2i2c Hub. For example, you can create lectures from Jupyter Notebooks, and allow students to grab their own copy of the notebook to interact with on the 2i2c Hub. - -To connect your public content with a 2i2c Hub, we recommend using [Jupyter Book](https://jupyterbook.org). This is an open-source project that allows you to share collections of notebooks and markdown files as an online website and book. Check out the [Jupyter Book getting started guide](https://jupyterbook.org/start/overview.html) for more information about Jupyter Book. - -You can tell Jupyter Book to place links *directly to your 2i2c Hub* on each page that is served from a notebook. To do so, follow the [launch buttons for JupyterHubs instructions](https://jupyterbook.org/interactive/launchbuttons.html#jupyterhub-buttons-for-your-pages). Make sure that you configure your `jupyterhub_url` to point to the URL of your 2i2c Hub (e.g., `https://.pilot.2i2c.cloud`). - - -(include-content)= -## Include content in your hub - -To include content in your hub (e.g., scripts, notebooks, etc) we recommend using [`nbgitpuller`](https://jupyterhub.github.io/nbgitpuller). - -You can use `nbgitpuller` to generate a link to a public repository, or a file in that repository. When a user clicks that link, a copy of the link's target will be automatically placed in the user's home directory, and they will be directed to that content in the JupyterHub (if they are logged in). - -- **Generate an nbgitpuller link** by going to [`nbgitpuller.link`](http://nbgitpuller.link/). You'll be asked to provide some information about the content you wish to share, and can copy the link when you are done. - - Use `https://.pilot.2i2c.cloud` as your JupyterHub address - - Fill in the GitHub repository where your content exists (along with an optional file path or branch name) - - The link will be in the field just above your form. - -- **Share this link with your users**. Anybody can click an `nbgitpuller` link. If they have an account on the hub to which it points, then they'll get a copy of the content that you've linked to. - -:::{admonition} Double-check your hub URL -:class: important -Make sure that the hub URL you insert into the nbgitpuller form is correct! See [](note-on-urls) for more information. -::: - -```{link-button} http://nbgitpuller.link -:text: Go to nbgitpuller.link -:classes: btn-outline-primary btn-block -``` -```{figure} ../images/nbgitpuller-ui.png -The [`nbgitpuller.link`](http://nbgitpuller.link) user interface, along with some important fields highlighted. -``` \ No newline at end of file diff --git a/admin/data.md b/admin/data.md deleted file mode 100644 index 2bcee59..0000000 --- a/admin/data.md +++ /dev/null @@ -1,33 +0,0 @@ -# Data access and sharing - -## Share data and files across users - -Hubs have a folder called `shared` that is meant for distributing files, data, etc that **all users have access to**. This can be useful for utilizing a shared resource on the hub so that all students don't have to download it themselves (for example, a dataset that is commonly-used in course material). - -The `shared` folder is **read-only**, and accessible by *all* users. There is also a `shared-readwrite` folder that has **write and read** privileges, and **only accessible by hub administrators**. All files placed in `shared-readwrite` will show up in `shared` for users. - -To share files across users, follow these steps: - -- **Hub Aministrators** put files in `shared-readwrite`. - - e.g. on an admin account, put a CSV file in a location like: - - ``` - ~/shared-readwrite/myshareddata.csv - ``` -- **Users access those files** in their code. E.g., run code like: - - ```python - import pandas as pd - pd.read_csv("~/shared/myshareddata.csv") - ``` - -```{seealso} -To share *content* that is stored in a public repository, see [](include-content). -``` - -## User storage - -Each user gets their own storage that persists across user sessions. -These files are only accessible to the user and to hub administrators. -However, see the other sections on this page for ways to share content and data between users. diff --git a/admin/environment.md b/admin/environment.md deleted file mode 100644 index d9d9a6e..0000000 --- a/admin/environment.md +++ /dev/null @@ -1,36 +0,0 @@ - - -# Your hub's environment - -## Where is your hub configured? - -All of the infrastructure that 2i2c deploys uses standard open source tooling and configuration. This means that the configuration for your JupyterHub can be modified just as if you were deploying it yourself. The [`pilot-hubs` repository](https://github.com/2i2c-org/pilot-hubs) has information about the configuration for each hub that 2i2c supports. For example, [this configuration file](https://github.com/2i2c-org/pilot-hubs/blob/master/hubs.yaml) has configuration for a collection of hubs. Each entry (corresponding to one hub) has [a Zero to JupyterHub configuration](https://zero-to-jupyterhub.readthedocs.io/en/latest/resources/reference.html). This can be modified to customize your hub's setup. - -## The default user environment - -The default environment for all pilot hubs is defined [in this folder](https://github.com/2i2c-org/low-touch-hubs/tree/master/images/user). It is a bit technical, but gives an idea of the kinds of libraries that are installed by default. - -In particular: - -- For Python: [see this `environment.yml` file](https://github.com/2i2c-org/low-touch-hubs/blob/master/images/user/environment.yml) for common Python packages -- For R: [see this `install.R` file](https://github.com/2i2c-org/low-touch-hubs/blob/master/images/user/install.R) - -In addition, some [types of hubs](hub-types) have modifications (usually additions) to this software environment. - -(environment/custom)= -## Customize your hub's environment - -There are two ways that you can customize your hub's environment: - -- **Temporarily `pip install` the packages you wish**. These will be installed **for your current session only**, and will be removed if your server stops and re-starts. As such, we recommend putting a collection of `!pip install` commands in the first cell of your notebooks that need extra libraries. -- **Request an update to the hub environments**. To request a new or updated package, [open an issue in the `2i2c-org/pilot` repository](https://github.com/2i2c-org/pilot/issues/new?labels=enhancement&template=tech-request.md) and ask for the new package to be installed. -- **Bring your own Docker image**. You may also use your own Docker image. Simply push your image to a public registry, and [open an issue in the `2i2c-org/pilot-hubs` repository](https://github.com/2i2c-org/pilot-hubs/issues/new) to request that your image be used. In the issue, include the public registry, image name, and tag that you wish to use. - - See the [pilot hubs custom image documentation](ph:custom-image) for information about the requirements for these Docker images. - -We are working on ways to let individual hubs customize their environment on their own, and will update these docs when that happens! - -:::{admonition} Try to avoid installing packages in the user directory -:class: note -Each of your users has their own filesystem that persists across sessions, so it is technically possible to use `pip install --user` to install packages to the home directory so they persist across sessions. However, this is discouraged because it often leads to mismatches between user and instructor environments, and may break functionality on the hub if packages are updated in the base environment that clash with a user-installed package. -::: diff --git a/admin/howto/control-user-server.md b/admin/howto/control-user-server.md new file mode 100644 index 0000000..ea4bb2b --- /dev/null +++ b/admin/howto/control-user-server.md @@ -0,0 +1,58 @@ +# Controlling a user's server + +Hub admins can unilaterally perform actions on a user's server via the +**Administrator's Panel**. These are primarily used to debug a user's session +easily. + +You can access the admin panel by clicking the {guilabel}`Admin` button in the top bar +in your hub control panel. Alternatively, you can go to this URL in your +browser: `https:///hub/admin`. + + +## Access a user's server + +Accessing a user's server is useful when trying to debug or reproduce an issue they might have. This facility is available to admins via the admin panel. + +1. In the admin panel, you can click {guilabel}`access server` to gain control of a user's + currently running server. If it isn't running, you can click {guilabel}`start server` + first and wait for it to start. + + ```{figure} ../../images/access-server.png + Clicking "access server" will allow you to control the user's session. + ``` + +2. This will bring you to the default interface that the user would have seen if they had just logged into the hub. From here, you can navigate to the notebook the user has reported issues with, and help them debug. + + :::{warning} + If you both work on the same notebook at the same time, you will just + overwrite each other's code! The state of the notebook will be that of + whoever saved the notebook last. There is no Google Docs' style + real-time collaboration yet, although [it is coming](https://github.com/jupyterlab/rtc) + ::: + + :::{warning} + When you control a user's server, all of your actions will be run *as + if the user ran it themselves*. This can be confusing for some users + and is generally not best-practice. We recommend telling users when + you are taking over their session, and using this feature mostly to understand what the user was trying to do, rather than to make major + changes to their code or notebook outputs. + ::: + +(user-server/stopping)= +## Stop or start a user's server + +Sometimes, you need to just turn a user's server on and off. You can +also do this from the admin interface, by hitting the {guilabel}`Stop server` +button, waiting for the server to stop, and the {guilabel}`Start server` button +again. + +This is particularly useful when their session might have gotten +out of whack by packages they've installed temporarily that screwed up +the default, since a restart will wipe the slate clean. + +:::{important} +When a user's server is stopped (by an admin, or by the user themselves), no data is lost in the user's home directory. +However, any packages temporarily installed via `!pip` or `!conda` are cleared, to make sure that everyone in the hub is operating from the same clean environment as much as +possible. +Active notebooks have their kernel killed as well. +::: diff --git a/admin/howto/create-content.md b/admin/howto/create-content.md new file mode 100644 index 0000000..545cd9a --- /dev/null +++ b/admin/howto/create-content.md @@ -0,0 +1,24 @@ +# Create content for your Hub + +## Write public books that connect to a 2i2c Hub + +You can create public content that is designed to connect with your +2i2c Hub. For example, you can create lectures from Jupyter Notebooks, and allow +students to grab their own copy of the notebook to interact with on the 2i2c +Hub. + +To connect your public content with a 2i2c Hub, we recommend using [Jupyter +Book](https://jupyterbook.org). This is an open-source project that allows you +to share collections of notebooks and markdown files as an online website and +book. Check out the [Jupyter Book getting started +guide](jb:start/overview) for more information about +Jupyter Book. + +You can tell Jupyter Book to place links *directly to your 2i2c Hub* on each +page that is served from a notebook. To do so, follow the [launch buttons for +JupyterHubs +instructions](https://jupyterbook.org/interactive/launchbuttons.html#jupyterhub-buttons-for-your-pages). +Make sure that you configure your `jupyterhub_url` to point to the URL of your +2i2c Hub (e.g., `https://.pilot.2i2c.cloud`). +This will use automatically [create nbgitpuller links](nbgitpuller.md) +for you. diff --git a/admin/howto/environment.md b/admin/howto/environment.md new file mode 100644 index 0000000..756c3d2 --- /dev/null +++ b/admin/howto/environment.md @@ -0,0 +1,91 @@ +# Modify your hub's user environment + +When your users log in to their hub, they are presented with a +configured environment with base libraries, user interfaces and +languages installed. This allows them to start working immediately, +without having to install packages themselves. + +## Default user environment + +The default environment for all pilot hubs is defined [in this +folder](https://github.com/2i2c-org/pilot-hubs/tree/master/images/user). +It is configured with the following: + +- Python packages defined in[this `environment.yml` + file](https://github.com/2i2c-org/pilot-hubs/blob/master/images/user/environment.yml). Many common scientific python packages are installed here. +- R packages installed from [this `install.R` + file](https://github.com/2i2c-org/pilot-hubs/blob/master/images/user/install.R). +- Many popular data science user interfaces installed: + - [Classic Jupyter Notebook](https://github.com/jupyter/notebook/) + - [JupyterLab](https://github.com/jupyterlab/jupyterlab/) + - [RStudio](https://rstudio.com/) +- An Ubuntu 20.04 base image, with common utility packages installed. + +(environment/custom)= +## Customizing your hub environment + +Sometimes, what is in the base user environment is not enough for +your use case. You might need new packages installed, a different +language version, etc. Here are a few ways to customize yours. + +### Ask for changes to the base image + +If you only need one / two extra packages, the easiest way is to +[open an issue in the `2i2c-org/pilot` repository](https://github.com/2i2c-org/pilot/issues/new?labels=enhancement&template=tech-request.md) +and ask for the new package to be installed. This is often the simplest +way forward. + +### Bring your own docker image + +Our hubs use [docker images](https://www.docker.com/) to provide the +user environment. You can build and bring your own docker image, +which gives you *full control* over your environment. + +We recommend the following setup for building & maintaining your +docker image: + +1. Create a GitHub repository that will contain just your *environment* files, + not content. You could use just files that help [create your environment on + mybinder.org](https://repo2docker.readthedocs.io/en/latest/config_files.html) - like `environment.yml` or `requirements.txt` for python, + `install.R` for R, etc. You can also instead have a `Dockerfile` + for full control. Another popular option is to use a `Dockerfile` but + inherit from a [pangeo base image](https://github.com/pangeo-data/pangeo-docker-images), + making just the modifications you need. + +2. Use the [repo2docker GitHub Action](https://github.com/jupyterhub/repo2docker-action) + to automatically build, name and push your image to a docker registry. + We recommend [pushing to quay.io](https://github.com/jupyterhub/repo2docker-action#push-image-to-quayio), + a registry with more generous rate limits than DockerHub's. You can + [use DockerHub](https://github.com/jupyterhub/repo2docker-action#push-repo2docker-image-to-dockerhub), + or any other public registry. + + +3. [Open an issue in the `2i2c-org/pilot` repository](https://github.com/2i2c-org/pilot/issues/new?labels=enhancement&template=tech-request.md) + with a link to your docker image. 2i2c hub engineers can then + configure your hub to use the new image. + + ```{note} + Currently, you need to open an issue *every time your base environment changes*. This will hopefully be a bit more streamlined + in the future. + ``` + +### Temporarily install packages for a session + + +You can temporarily install packages in your environment that will +just last the duration of your user session. They will get wiped out +when your user server is stopped, to ensure that you always start from +a 'clean slate' environment. + +The recommended way is to put `%pip install ` or +`%conda install ` in the first cell of any notebook +you distribute, so when run it'll install necessary packages. For R, +you can use `install.packages("package-name")` as you normally would. + +```{warning} + +While tempting, do not use `!pip install --user ` to install +packages. This makes the base environment different for different users, +causing hard to debug issues. This could also render your user server +unable to start, due to conflicting packages. +``` diff --git a/admin/howto/manage-users.md b/admin/howto/manage-users.md new file mode 100644 index 0000000..5227b13 --- /dev/null +++ b/admin/howto/manage-users.md @@ -0,0 +1,43 @@ +# Manage access to the hub + +The **Administrator Panel** can be used to maintain the list of users +who are authorized to use your hub. You can access this panel by clicking +the 'Admin' button in the top bar in your hub control panel. +Alternatively, you can go to this URL in your browser: +`https:///hub/admin` + +## To add users + +1. Click the {guilabel}`Add Users` button. The {guilabel}`Add Users` dialog box will pop up. +2. Add one or more users, and hit the {guilabel}`Add Users` button to authorize all the users you just added. + + +````{panels} +:container: full-width +:card: border-1 +```{figure} ../../images/add-users-button.png +The {guilabel}`Add Users` button in the Administrator Panel. +``` +--- +```{figure} ../../images/add-users-form.png +Fill in usernames and optionally make them administrators. You can add multiple users at once by putting a username on each line. +``` +```` + +## Finding usernames + +Access is granted or revoked based on `usernames`, and these depend on the kind +of (authentication provider)[admin/configuration/authentication] your hub is +using. In general, it matches whatever the visible 'username' in your +authentication provider is. The table below lists the available providers, and +how to determine their username. + + +| Provider | Username | +|-|-| +| Google | Email address | +| GitHub | GitHub user name | +| ORCID | ORCID id | + + +% TODO: Document how to remove users diff --git a/admin/howto/nbgitpuller.md b/admin/howto/nbgitpuller.md new file mode 100644 index 0000000..eba7def --- /dev/null +++ b/admin/howto/nbgitpuller.md @@ -0,0 +1,82 @@ +# Distribute content with nbgitpuller + +You'll often want to distribute *content* (such as notebooks, scripts, sample +data, etc) to your users so they can do exercises, follow along with a lecture, +or use as a starting point for their own work. This content is often constantly +updated as time goes on, and needs to not overwrite your student's work if you +make an adjustment to content that has already been touched by the student. + + +[nbgitpuller](https://jupyterhub.github.io/nbgitpuller) is the tool +we recommend for this. The workflow goes something like this: + +## Put your content in a public GitHub repository + +Create a repository on [GitHub](https://github.com) and start putting your +content there. This is the *source* of the content that will be distributed +to your users. You can update it as often as you wish. While instructors will +need to know how github works, *your users will never have to interact with +git directly*. + +## Generate an nbgitpuller link + +Generate an [nbgitpuller link](http://nbgitpuller.link). This generates a +*clickable link* that contains within it the following pieces of information: + +1. The URL to your hub. Upon clicking the link, users will be redirected to + this hub, and content will be pulled into their home directory there. +2. The URL of the git repository where the content lives. +3. The branch in the git repository where the content lives. The default + specified there is `master`, although newer GitHub repositories use `main` + as the default. You can find yours on the Github page of your content + repository +4. The default interface to open when users click this link. The default is + the classic notebook, but many other apps are available. +5. A file to open when the link is clicked. When left empty, a directory + listing with the content of the repository will be shown. + +```{figure} ../../images/nbgitpuller-ui.png +The [`nbgitpuller.link`](http://nbgitpuller.link) user interface, along with +some important fields highlighted. +``` + +```{tip} +Unfortunately, RStudio does not support opening a specific file, and will +always show the home directory. Users will have to manually navigate to +the appropriate file. +``` + +Once you've filled these out, you can copy the link from the textbox above the form. + +## Distribute your nbgitpuller link + +Distribute the link you have generated to your users. Upon clicking the link, +they will be: + +1. Redirected to your hub, and asked to log in if they have not already +2. The first time the link is clicked, your content repository will be pulled + into their home directory! +3. If they had already clicked the link before, any new changes in your + content repository will be pulled in. Any changes the user has made will + be [automatically + merged](https://jupyterhub.github.io/nbgitpuller/topic/automatic-merging.html) + with changes in the content repository, in such a way that the user's + changes are never overwritten. All merge conflicts will also be + automatically resolved, so users don't have to interact with git. +4. If you have picked a specific file to be displayed, the user will be + redirected to that file, open in the application you picked. If not, the + directory listing of local copy of the content repository will be shown in + the application you selected. + +:::{important} + +You **do not** have to create a new link each time you update your content +repository! The same link will continue to work, so you can simply ask your +users to click the link again to fetch the latest changes. + +However, if you want to create links to individual files that should be +opened at specific points - like one link per class or assignment - you can +regenerate the links with different values for the file to open or interface. +As long as the hub url, content repository url and the branch name are the +same, users will be not be duplicating content. +::: diff --git a/admin/howto/share-datasets.md b/admin/howto/share-datasets.md new file mode 100644 index 0000000..7517624 --- /dev/null +++ b/admin/howto/share-datasets.md @@ -0,0 +1,41 @@ +# Share data files with your users + +Sometimes you might need to distribute a set of files to all +your users, so they don't have to re-download it once per person. +This is particularly useful in educational contexts, where you might +be teaching a course that reads a common dataset. + +```{warning} +If you are teaching with large datasets, you might run out of +memory! So consider teaching with just a subset of data before +distributing large datasets to your users. +``` + +## The `shared` directory + +There are two folders that are used together to allow Administrators to +share data files with all users. + +`shared` +: All users have a directory called `shared` in their home directory. + This is a *readonly* directory - users and administrators can not write to it. + However, anybody can *access* and *read from* the `shared` directory. + This is how a user accesses a data file distributed by a hub administrator. + +`shared-readwrite` +: **(administrators only)** Admin users also have a directory called `shared-readwrite` in their home directory. + This is the *same folder* as the `shared` directory, but writeable! + Any files admins put here will be immediately visible in all users' `shared` directories. + +## A workflow for sharing datasets + +To share datasets with users, admins should put the dataset in +`~/shared-readwrite`. If they are distributing notebook / content +that *reads* this dataset, it should refer to files in `~/shared/` +rather than in `~/shared-readwrite`. This will prevent accidental +erasures / writes on behalf of admins. + +```{warning} +This is an experimental feature, and the names of these directories +and their structure are subject to change. +``` diff --git a/admin/support.md b/admin/howto/support.md similarity index 100% rename from admin/support.md rename to admin/howto/support.md diff --git a/admin/interfaces.md b/admin/interfaces.md deleted file mode 100644 index a79b497..0000000 --- a/admin/interfaces.md +++ /dev/null @@ -1,41 +0,0 @@ -# Administrator interfaces - -## The Administrator Dashboard - -The JupyterHub administrator dashboard allows you to control several aspects of your JupyterHub. It is available via most of the user interfaces on your hub, as well as at the following URL: - -``` -https://.pilot.2i2c.cloud/hub/admin -``` - -:::{note} -The administrator panel will only be available to user names you have explicitly requested to be administrators! -::: - -```{figure} ../images/admin-panel.png -An example administrator's panel -``` - -From the administrator panel, you can see several columns and buttons: - -`User` -: The username of each user in your 2i2c Hub (both logged-in and logged-out) - -`Admin` -: Whether that user is an administrator - -`Last Activity` -: The last time that the user's server logged any activity (e.g. opening a file, running code, or logging in). - -`Running` -: Whether the user's server is currently running. You may also **start or stop a user's server** from this column. - -`Shutdown Hub` -: Shutdown the hub for all users (it may be restarted as well). - -`Edit User` -: Edit the username information or make a user an administrator. - -`access server` -: Take over the user's session so that you may inspect what they are doing (this is helpful for debugging). - diff --git a/admin/migrate.md b/admin/migrate.md deleted file mode 100644 index 968bf88..0000000 --- a/admin/migrate.md +++ /dev/null @@ -1,66 +0,0 @@ -(migration-guide)= -# Migrating off of a 2i2c Hub - -2i2c Hubs are designed to use entirely open source tools that are vendor- and workflow-agnostic. Our goal is to provide you with interactive computing environments that seamlessly integrate with pre-existing workflows across the research and education community. That means we want it to be **extremely easy to move off of a 2i2c Hub**. This section has a few tips for how you can move off of a 2i2c Hub and into a different environment that uses the Jupyter stack. - -## The 2i2c Hubs for All deployment repository - -If you'd like to see the configuration and deployment scripts for the Hubs for All pilot, you can find it at [the `2i2c-hubs` configuration repository](https://github.com/2i2c-org/pilot-hubs). This is more complex than setting up a single JupyterHub, since it manages the entire federation of 2i2c Hubs in this pilot. You can also find [our documentation for running and configuring hubs with this repository](https://2i2c.org/pilot-hubs/). - -## Different ways to re-create your environment without 2i2c - -### Deploy your own JupyterHub - -2i2c Hubs are an opinionated collection of open source tools, customized for research and education. Using an entirely open stack means that you can deploy these tools yourself if you wish. The first step is to deploy your own JupyterHub, which can run on a variety of cloud vendors (or even your own hardware). - -[The Zero to JupyterHub for Kubernetes guide](https://z2jh.jupyter.org) is an opinionated guide to deploying JupyterHub on Kubernetes. The 2i2c team has written much of the content in this guide, and encourages you to follow it in deploying your own hub infrastructure! The 2i2c Hubs use much of the steps in this guide for their deployment. They also use the [JupyterHub Helm Chart](https://github.com/jupyterhub/helm-chart) in order to deploy JupyterHub in a scalable and flexible way. - -:::{tip} -If you'd like a more lightweight distribution of JupyterHub, you can try out [The Littlest JupyterHub](https://tljh.jupyter.org). This distribution of JupyterHub is easier to set up for smaller teams. -::: - -### Re-create the user environment locally - -The `pilot-hubs` repository has [the configuration for default user environments](https://github.com/2i2c-org/pilot-hubs/tree/master/../images/user). These scripts and files are used to create the Docker image that is used in a 2i2c Hub. We upload that Docker image to a registry and then [configure each JupyterHub to use it here](https://github.com/2i2c-org/pilot-hubs/blob/master/hub/values.yaml#L85). - -For more information about creating custom environments for a JupyterHub, we recommend checking out the [repo2docker project](https://repo2docker.readthedocs.io/), which builds Docker images from Binder repositories. - -### Use a different managed cloud service - -Finally, if you wish to use a different managed cloud service, there are many for you to choose from. These tend to have proprietary components interwoven with open-source ones, which can be a "pro" or a "con" depending on your use-case. 2i2c Hubs are designed to be 100% open source and interoperable with a variety of cloud vendors, however your workflows may be transportable to a proprietary cloud service just the same. - -## Download your content and data - -(download-as-pdf)= -### Download your notebooks as PDFs - -2i2c Hub come with the ability to convert a Jupyter Notebook as a PDF that users may download locally. To do so, use the Jupyter interface of your choice as shown below: - -````{panels} -:container: full-width -:column: + text-center -Classic Notebooks -```{figure} ../images/download-latexpdf-classic.png -:height: 300px -``` ---- -JupyterLab -```{figure} ../images/download-latexpdf-lab.png -:height: 300px -``` -```` - - -(download-user-files)= -### Download your data from a hub - -If you'd like to stop using your 2i2c Hub, or would simply like to move your data onto your own machine (or elsewhere in the cloud), take the following steps to download your data locally: - -1. Navigate to the Jupyter "tree" view by changing your URL path to `/tree`. e.g., `.pilot.2i2c.cloud/user//tree` -2. Click on **`Download Directory`**. - - ```{figure} ../images/download-directory.png - :alt: The download directory button - ``` - -This will zip up the contents of your user file system and download them to your machine. diff --git a/admin/users.md b/admin/users.md deleted file mode 100644 index c5868ba..0000000 --- a/admin/users.md +++ /dev/null @@ -1,44 +0,0 @@ -# Managing users and their sessions - - -(add-users)= -## Add / remove users - -To add or remove users for your 2i2c Hub, go to the **Administrator Panel** and click on the `Add Users` button. This will allow you to add one-or-more users to the hub. - -The types of usernames you add will depend on the kind of authentication you've requested for your hub (e.g., email addresses vs user names). - -````{panels} -:container: full-width -:card: border-1 -```{figure} ../images/add-users-button.png -The add users button in the Administrator Panel. -``` ---- -```{figure} ../images/add-users-form.png -Fill in usernames and optionally make them administrators. You can add multiple users at once by putting a username on each line. -``` -```` - -(access-server)= -## Take control of a user's server - -If you'd like to debug a user's server, you may take control over their session by clicking the **access server** button. This will show you the latest file that they were working on. This is particularly useful for helping them debug a problem with their session. - -```{figure} ../images/access-server.png -Clicking "access server" will allow you to control the user's session. -``` - -```{warning} -When you control a user's server, all of your actions will be run *as if the user ran it themselves*. This can be confusing for some users and is generally not best-practice. We recommend telling users when you are taking over their session, and using this feature mostly to understand what the user was trying to do, rather than to make major changes to their code or notebook outputs. -``` - -## User session duration - -After 1h of *inactivity*, the user's session is culled. This stops all running -notebooks & terminals. They can start them back up again on login - their home -directories are preserved. Any packages they've temporarily installed with `!pip` -or `!conda` are also cleared, so they might have to install them again. - -There is no total time limit on how long a user's session -can last. diff --git a/conf.py b/conf.py index cee4dde..fe85a60 100644 --- a/conf.py +++ b/conf.py @@ -57,7 +57,8 @@ html_logo = "images/logo.png" intersphinx_mapping = { "tc": ('https://2i2c.org/team-compass', None), - "ph": ('https://2i2c.org/pilot-hubs', None) + "ph": ('https://2i2c.org/pilot-hubs', None), + "jb": ('https://jupyterbook.org', None) } rediraffe_redirects = { diff --git a/images/download-latexpdf-classic.png b/images/download-latexpdf-classic.png deleted file mode 100644 index 60bc7cd..0000000 Binary files a/images/download-latexpdf-classic.png and /dev/null differ diff --git a/images/download-latexpdf-lab.png b/images/download-latexpdf-lab.png deleted file mode 100644 index 91c33a6..0000000 Binary files a/images/download-latexpdf-lab.png and /dev/null differ diff --git a/index.md b/index.md index b3b9166..f8ed6ca 100644 --- a/index.md +++ b/index.md @@ -8,30 +8,54 @@ This guide is for **administrators and community champions** of 2i2c Hubs, or fo See the sections below (or to the left) for more information. +## About the 2i2c hubs ```{toctree} -:caption: About the 2i2c Hubs :maxdepth: 1 +:caption: About the 2i2c hubs about/overview about/infrastructure about/projects ``` +## Hub configuration options + +These pages list the different ways hub admins can configure how +their hub behaves. Most of them require working with a 2i2c engineer +to realize the configuration option. + ```{toctree} -:caption: Administrator Guide :maxdepth: 1 +:caption: Hub configuration options -admin/support -admin/environment -admin/interfaces -admin/data -admin/users -admin/migrate -admin/content +admin/configuration/login +admin/configuration/culling ``` +## Hub administrator how-to guides + +These guides have information on how hub admins can perform specific +tasks on their hubs, mostly without requiring any interaction with +2i2c engineers. + ```{toctree} :maxdepth: 1 -:caption: User's Guide -users/interface -``` \ No newline at end of file +:caption: Administrator how-to guides +admin/howto/support +admin/howto/environment +admin/howto/nbgitpuller +admin/howto/create-content +admin/howto/manage-users +admin/howto/control-user-server +admin/howto/share-datasets + +``` + +## Hub user guides + +```{toctree} +:maxdepth: 1 +:caption: User guides +user/download-data +user/interface +``` diff --git a/user/download-data.md b/user/download-data.md new file mode 100644 index 0000000..8dd2ea5 --- /dev/null +++ b/user/download-data.md @@ -0,0 +1,26 @@ +# Download your home directory + +You might want to download your entire home directory for many +reasons - to get data off a hub that is closing, to migrate to +a different service, for archival purposes, etc. Your home directory +will contain all your data *and* your notebooks. +Hubs managed by 2i2c make this easy. + +1. **Open the classic Jupyter Notebook file browser.** If you are + using another interface, navigate to the classic interface by changing your + URL path to `/tree`. e.g., + `.pilot.2i2c.cloud/user//tree` + +2. Click on **`Download Directory`**. + + ```{figure} ../images/download-directory.png + :alt: The download directory button + ``` + +This will zip up the contents of your user file system and download them to your machine. + +:::{note} +If your hub is using a [custom user environment](environment/custom), it needs the +[jupyter-tree-download](https://github.com/ryanlovett/jupyter-tree-download) package +installed to make this feature available. +::: diff --git a/users/interface.md b/user/interface.md similarity index 82% rename from users/interface.md rename to user/interface.md index acdd84e..1e94f4e 100644 --- a/users/interface.md +++ b/user/interface.md @@ -12,4 +12,4 @@ You can replace the contents of `` to be one of the following: - **Jupyter Notebook**: `/tree` - **RStudio**: `/rstudio` -Note that your 2i2c Hub administrator can also configure the **default** interface that users see. In addition, you can configure the interface that **nbgitpuller links** point to, see [](include-content) for information about nbgitpuller links. +Note that your 2i2c Hub administrator can also configure the **default** interface that users see. In addition, you can configure the interface that **nbgitpuller links** point to, see [](../../admin/howto/nbgitpuller.md) for information about nbgitpuller links.