Re-organize documentation to match new structure

admin/configuration/culling.md

@@ -0,0 +1,17 @@
+# 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
+
+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,35 @@
+# 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.
+
+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 strictly 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.
+
+Currently, there are only two supported methods for authorizing regular users:
+
+1. [Manually add users](admin/howto/manage-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 users are instead authorized [in 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

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 a 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 your
+browser: `https://<your-hub-url>/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 `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/create-content.md

@@ -0,0 +1,25 @@
+# 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://<your-hub>.pilot.2i2c.cloud`).
+This will use automatically [create nbgitpuller links](admin/howto/nbgitpuller)
+for you.
+

admin/howto/environment.md

@@ -0,0 +1,90 @@
+# 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.
+
+## 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 <list-of-packages>` or
+`%conda install <list-of-packages>` 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 <packages>` 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.
+```

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://<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 |
+
+
+% TODO: Document how to remove users