Re-organize documentation to match new structure

admin/configuration/culling.md

@@ -0,0 +1,11 @@
+# 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.
+
+This has the same effect as a user stopping their own server. User servers stopping doesn't lose any data in your home directories. 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.
+
+There is currently no maximum time limit for a user's notebook.

admin/configuration/login.md

@@ -0,0 +1,25 @@
+# User authentication & authorization
+
+(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 could probably 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.
+
+## 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.
+
+Currently, there are only two supported methods:
+
+1. Manually add users via the admin panel in JupyterHub
+2. (Google only) Allow all users who are logged in via aparticular domain - so you can allow access to anyone who is part of your organization or educational institution.
+

admin/content.md

@@ -8,30 +8,3 @@ To connect your public content with a 2i2c Hub, we recommend using [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://<your-hub>.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://<your-hub>.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.
-```

admin/howto/control-user-server.md

@@ -0,0 +1,48 @@
+# Controlling a user's server
+
+Hub admins can unilaterally perform actions on user's servers via the
+**Administrator's Panel**. These are primarily used to debug user's session
+easily.
+
+You can access the admin panel by clicking the 'Admin' button in the top bar
+in your hub control panel.  Alternatively, you can go to this URL in our
+browser: `https://<your-hub-url>/hub/admin`.
+
+
+## Access a user's server
+
+Accessing a user's server is very 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 `access server` to gain control of a user's
+   currently running server. If it isn't running, you can click `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.
+    ```
+
+## Stopping & starting 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 `Stop server`
+button, waiting for the server to stop, and the `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.

admin/howto/manage-users.md

@@ -0,0 +1,45 @@
+# 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://<your-hub-url>/hub/admin`
+
+## To add users
+
+1. Click the `Add Users` button. The `Add Users` dialog box will pop up.
+2. Add one or more users, and hit the `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 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 |
+
+
+## To remove users
+
+????

admin/howto/nbgitpuller.md

@@ -0,0 +1,73 @@
+# 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:
+
+1. 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*.
+
+2. 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.
+
+3. 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.
+
+4. 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.

admin/howto/share-datasets.md

@@ -0,0 +1,33 @@
+# Share large data files with your users
+
+Sometimes you might need to distribute a set of large 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.
+```
+
+All users have a directory called `shared` in their home directory.
+This is meant to be used to distribute datasets and other files that
+can be read by all users. This is a *readonly* directory - regular
+users can not write to it.
+
+Admin users will also have a directory called `shared-readwrite` in
+their home directory. This is the *same* as the `shared` directory,
+but writeable! So any files admins put here will be immediately
+visible in all users' `shared` directories.
+
+So 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 is subject to change.
+```