Re-organize documentation to match new structure (#55)

Co-authored-by: Chris Holdgraf <choldgraf@berkeley.edu>

about/infrastructure.md

@@ -84,6 +84,7 @@ Each 2i2c Hub has **hub name** (denoted by `<hub-name>`) 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.

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?
 

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.

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. `<a different provider>`. 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

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://<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 {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.
+:::

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://<your-hub>.pilot.2i2c.cloud`).
+This will use automatically [create nbgitpuller links](nbgitpuller.md)
+for you.