Reorganize docs, add several new guides

packages/apollo-cli/package.json

@@ -30,7 +30,7 @@
     "posttest": "yarn lint",
     "test:ci": "nyc mocha 'src/**/*.test.ts'",
     "test:cli": "yarn tsx src/test/test.ts",
-    "version": "oclif readme --multi --dir ../website/docs/admin/cli/ && oclif readme && git add README.md"
+    "version": "oclif readme --multi --dir ../website/docs/03-guides/04-cli/ && oclif readme && git add README.md"
   },
   "oclif": {
     "bin": "apollo",

packages/website/docs/01-try-it-out/01-ways-to-try-it-out.md

@@ -0,0 +1,47 @@
+# Ways to try out Apollo
+
+There are a few different ways you can try out Apollo, ranging from taking a
+quick look to provisioning a full multi-user installation.
+
+## Check out our quick-look demo
+
+To quickly see what Apollo looks like and get a basic idea of its functionality,
+visit this link:
+
+[Try Apollo now!](https://demo.apollo.jbrowse.org/?session=share-oPRJK2yMUq&password=qMrK4)
+
+Log in either as a guest or use a Google account.
+
+The genome annotation database you see when you open this link represents a
+small slice of a genome stored directly in your JBrowse session. This genome
+database is not collaborative: anything you change is limited to your current
+browsing session and is only visible to you. Anything you do on this genome also
+won't affect anyone else's experience, so feel free to experiment however you
+like. If you want to start fresh again without any of your changes, you can open
+the original link again.
+
+## Try our full public demo
+
+If you want to explore some larger genome annotation databases that are
+collaborative (meaning any changes you make will be visible to other users),
+there are a few other genomes loaded on our demo server.
+
+Click the link given in the quick-look demo above, go to the "Add" menu and
+choose "Linear genome view," choose either "Schistosoma haematobium" or
+"Schistosoma mansoni," and click "Open". To see the Apollo track, open the track
+selector and choose the "Annotations" track.
+
+## Run Apollo on your own computer
+
+If you'd like to try setting up Apollo yourself, either with data we provide or
+with your own data, the
+[tutorial on the following pages](./local-demo/setting-up) walks you through
+setting up an Apollo instance that runs on your own computer, with all the steps
+for configuring the server and loading data. This is a great way to test Apollo
+out before doing a full multi-user installation
+
+## Install a full multi-user Apollo instance
+
+Our [installation guide](../installation/background) walks you through deploying
+a fully-featured multi-user Apollo instance on a server, allowing you to take
+advantage of Apollo's collaborative features to annotate your own genomes.

packages/website/docs/getting-started/try-it-out/01-setting-up.md → packages/website/docs/01-try-it-out/02-local-demo/01-setting-up.md

@@ -1,12 +1,12 @@
-# Setting up
+# Initial setup
 
 To run this demo, you'll need to have
 [Docker](//docs.docker.com/engine/install/) (minimum version 27) and
 [Docker Compose](//docs.docker.com/compose/install/) (minimum version 2.17.0)
 installed, as well as [`jq`](https://jqlang.github.io/jq/).
 
 We also recommend a Node.js package manager (such as `npm` or `yarn`) to make
-things a easier, but we will provide directions for doing everything without one
+things easier, but we will provide directions for doing everything without one
 that you can follow if you prefer.
 
 ## Getting the data

packages/website/docs/getting-started/try-it-out/02-loading-data.md → packages/website/docs/01-try-it-out/02-local-demo/02-loading-data.md

@@ -131,7 +131,7 @@ If you need to log in again, run `apollo logout` first, or use
 
 ## Adding assemblies and annotations
 
-The next step is to add an assembly. We're going to use trimmed-down assembly
+The next step is to add an assembly. We're going to use a trimmed-down assembly
 that only includes a single chromosome. This is so that the data is small enough
 to be self-contained inside this repository, without the need for any external
 data.
@@ -215,7 +215,7 @@ apollo jbrowse get-config > data/config.json
 
 Now that we have the configuration, we can use the `jbrowse` CLI tool to add the
 evidence tracks. We are using the `inPlace` value for the `--load` flag because
-we know how these files are going to be visible in to JBrowse, and we don't want
+we know how these files are going to be visible in JBrowse, and we don't want
 the CLI to try and copy or alter any files.
 
 ```sh

packages/website/docs/getting-started/try-it-out/03-annotating.md → packages/website/docs/01-try-it-out/02-local-demo/03-exploring/index.md

@@ -1,4 +1,4 @@
-# Annotating
+# Exploring Apollo
 
 Open a new browser tab and navigate to http://localhost.
 
@@ -31,7 +31,7 @@ the CDS is missing a stop codon.
 ![CDS warning](cds-warning.png)
 
 Click and drag in the ruler the area around the end of the CDS and then select
-"Zoom to region". We can see that the CDS stop short of the stop codon. Click
+"Zoom to region". We can see that the CDS stops short of the stop codon. Click
 and drag the right side of the CDS 3 bases to the right to fix it. Zoom back out
 so you can see the whole gene again, and you will see the warning about the stop
 codon is gone as well.
@@ -43,7 +43,7 @@ Now click the checkbox to open the RNA-seq track. It looks like this feature's
 track menu (the three dots next to the track name label) and select "Appearance
 -> Show both graphical and table display. A table showing the information about
 the current annotation is now shown at the bottom of the track. In the "gene"
-row, change then "end" value to `9659388`, and then do the same for the "mRNA"
+row, change the "end" value to `9659388`, and then do the same for the "mRNA"
 column.
 
 ![RNA-seq table editor](rnaseq-table-editor.png)
@@ -72,7 +72,7 @@ track and select "Track order -> Move track up".
 
 ![Synteny tracks](synteny-tracks.png)
 
-If you wanted to share this particular view, you can click the "Share" button at
+If you want to share this particular view, you can click the "Share" button at
 the top and copy the link. You can also use this for coming back to the same
 view later.
 
@@ -84,9 +84,9 @@ matches for that term. The one we're working on is the first match.
 ![Text search](search-text.png)
 
 Somewhere to the side of the existing gene, click and drag an area in the ruler
-and then select "Add new feature". Look a the possible ontology types suggested,
-and then choose "match". On the new feature, click "Add child feature" and
-choose the coordinates and "Match part" as the type.
+and then select "Add new feature". Look at the possible ontology types
+suggested, and then choose "match". On the new feature, click "Add child
+feature" and choose the coordinates and "Match part" as the type.
 
 Now right-click on the "match" feature and select "Delete feature".
 

packages/website/docs/01-try-it-out/02-local-demo/_category_.json

@@ -0,0 +1,3 @@
+{
+  "label": "Setting up a local demo"
+}

packages/website/docs/01-try-it-out/_category_.json

@@ -0,0 +1,3 @@
+{
+  "label": "Try out Apollo"
+}

packages/website/docs/getting-started/deployment/01-background.md → packages/website/docs/02-installation/01-background.md

@@ -42,7 +42,7 @@ The server requires Node.js 20 or higher to run as well as at least two CPU
 cores and 2GB Memory for basic usage. More memory will likely be required for
 larger assemblies or several concurrent users. The server also needs access to a
 location on its file system to save uploaded files. The size of hard drive it
-needs is dependant on how many files will need to be uploaded.
+needs is dependent on how many files will need to be uploaded.
 
 ### MongoDB Database
 
@@ -53,14 +53,14 @@ collaboration server, or it can be external.
 
 ## Deployment examples
 
-- [Deploying with Docker](./02-deployment-examples/01-docker-compose.md)
-- Other examples coming soon
+- [Deploying with Docker](../installation/examples/docker-compose)
+- [Deploying on Ubuntu](../installation/examples/ubuntu-server)
 
 ## Customizing your deployment
 
 Our deployment examples cover setting up Apollo with the most common default
 settings and guest user access. You'll most likely want to then configure user
-logins, which we cover in our [Login Management](03-login-management.md) guide.
+logins, which we cover in our [Login Management](login-management) guide.
 
 We also cover more options for customizing Apollo in our
-[Configuration options](04-configuration-options.md) guide.
+[Configuration options](./configuration-options) guide.

packages/website/docs/getting-started/deployment/02-deployment-examples/01-docker-compose.md → packages/website/docs/02-installation/02-examples/01-docker-compose.md

@@ -201,7 +201,7 @@ Docker command outputs.
 
 Next we're going to skip to the bottom section called `volumes`. In this compose
 file, we're using volumes to keep certain kinds of data around even if one of
-the containers needs to be rebuild. For example, let's say you're using a
+the containers needs to be rebuilt. For example, let's say you're using a
 MongoDB container that uses v7.0.6 of MongoDB, but you want to upgrade to
 v7.0.7. With Docker, instead of upgrading the running container, you usually
 build a brand new container based on a Docker image that has the new version you
@@ -381,7 +381,7 @@ mongo-node-1:
 
 This uses the official MongoDB image, runs on port 27017, and uses two volumes
 to store data and configuration in. The second node is almost identical, with a
-different and and port and without the `healthcheck` section.
+different port and without the `healthcheck` section.
 
 The `healthcheck` section is there to initialize the replica set the first time
 the container runs, and then to provide a way for the collaboration server to
@@ -419,9 +419,9 @@ And, you can stop Apollo by running
 docker compose down
 ```
 
-We are now ready to access Apollo. Open a web browser and got the URL you
+We are now ready to access Apollo. Open a web browser and get the URL you
 entered in the `apollo.env` file above. You should see a JBrowse instance with a
 prompt to log in as a guest. You should see a view with an assembly selector,
 but there aren't any assemblies yet. You're now ready to head over to our
-[Admin guide](../../../category/administrators) to learn how to load data into
+[assemblies guide](../../guides/assemblies) to learn how to load data into
 Apollo.

packages/website/docs/getting-started/deployment/02-deployment-examples/02-ubuntu-server.md → packages/website/docs/02-installation/02-examples/02-ubuntu-server/index.md

@@ -48,7 +48,7 @@ sudo systemctl restart apache2.service
 Now open the URL of your server. You should see a screen that says "It worked!".
 If so, JBrowse has been successfully installed.
 
-![Screen showing "It worked!" message](img/jbrowse_it_worked.png)
+![Screen showing "It worked!" message](jbrowse_it_worked.png)
 
 ## Set up Apollo JBrowse plugin
 
@@ -95,17 +95,17 @@ To save the file, press <kbd>Ctrl</kbd> + <kbd>O</kbd> and then
 Now open the same link as before (or refresh the page). You should now see the
 JBrowse start screen. Choose an "Empty" session.
 
-![JBrowse start screen](img/jbrowse_start_screen.png)
+![JBrowse start screen](jbrowse_start_screen.png)
 
 If Apollo has been installed successfully, you'll see a menu called "Apollo" at
 the top of the page.
 
-![Menu bar of JBrowse with an "Apollo" menu](img/apollo_top_menu.png)
+![Menu bar of JBrowse with an "Apollo" menu](apollo_top_menu.png)
 
-You can use some basic Apollo functionality like editing annotations small local
-GFF3 files with just the plugin, but to enable the full functionality of Apollo
-we'll need to add the last two components. Delete the `config.json` for now, as
-we won't need it anymore.
+You can use some basic Apollo functionality like editing annotations in small
+local GFF3 files with just the plugin, but to enable the full functionality of
+Apollo we'll need to add the last two components. Delete the `config.json` for
+now, as we won't need it anymore.
 
 ```sh
 rm config.json
@@ -216,7 +216,7 @@ sudo systemctl restart apache2
 ```
 
 The next thing we need to do is add a file that defines feature types for
-Apollo. This is usally the Sequence Ontology.
+Apollo. This is usually the Sequence Ontology.
 
 ```sh
 cd /var/www/html/
@@ -291,6 +291,6 @@ yarn start:prod
 Open the URL of your server. Open an "Empty" session, and then choose "Continue
 as Guest" in the dialog that appears.
 
-![Login dialog](img/apollo_login.png)
+![Login dialog](apollo_login.png)
 
 Congratulations, Apollo is now ready to use!

packages/website/docs/02-installation/02-examples/_category_.json

@@ -0,0 +1,3 @@
+{
+  "label": "Examples"
+}

packages/website/docs/getting-started/deployment/04-configuration-options.md → packages/website/docs/02-installation/04-configuration-options.md

@@ -1,4 +1,4 @@
-# Configuration options
+# Server configuration
 
 ```sh
 ##############

packages/website/docs/02-installation/_category_.json

@@ -0,0 +1,3 @@
+{
+  "label": "Installation"
+}

packages/website/docs/03-guides/01-administrators.md

@@ -0,0 +1,44 @@
+# Administrators
+
+In order to do things like add new assemblies, import annotations from a file,
+and manage the roles of other users, you will need to be an administrator. This
+means your user account will need to have the role of `Admin`.
+
+When Apollo is first set up, the first user who logs in is automatically made an
+administrator. Any other users who log in after that will be given the role set
+by `DEFAULT_NEW_USER_ROLE` in the
+[configuration options](../installation/configuration-options). An administrator
+can make another user into an administrator as well.
+
+There is also the option to have a single user, referred to as the "root user",
+with an `Admin` role that is able to authenticate without logging in via OAuth.
+This is meant to be used to simplify running CLI commands as an administrator.
+By default this user is disabled, but can be enabled with the `ALLOW_ROOT_USER`
+and `ROOT_USER_PASSWORD` options in the
+[configuration options](../installation/configuration-options).
+
+## How to access administrator capabilities
+
+There are two ways to access administrator capabilities in Apollo. The first is
+through the menus in the user interface. The top-level "Apollo" menu has a
+sub-menu called "Admin" that appears for those logged in as an administrator.
+These menu items include operations like adding assemblies and importing
+annotations.
+
+The second way to access administrator capabilities in Apollo is by using the
+Apollo CLI. The CLI provides the same options as using the GUI, but may be more
+useful for users who want to automate some of the administration tasks or who
+want to keep a log of what commands were run to set up Apollo.
+
+Each guide in this section will give instructions for both the GUI and the CLI,
+if applicable.
+
+## Common administrator actions
+
+Here are some of the most commonly-performed administrator tasks, and links to
+the guide that explains each one:
+
+- [Adding assemblies](assemblies)
+- [Importing annotation features](annotation-features)
+- [Managing users](users)
+- [Adding evidence tracks](evidence-tracks)