docs: cover the admin panel and the web app in Chek 0.5.0

astro.config.ts

@@ -5,7 +5,7 @@ import starlightOpenAPI, { openAPISidebarGroups } from "starlight-openapi"
 // The server release these pages describe. The API reference is built from
 // that release's openapi.yaml, so raise this when the guides catch up with a
 // new release, not before.
-const chekRelease = "0.3.0"
+const chekRelease = "0.5.0"
 
 export default defineConfig({
   site: "https://docs.chek.page",
@@ -38,6 +38,7 @@ export default defineConfig({
           items: [
             "self-hosting/install",
             "self-hosting/first-steps",
+            "self-hosting/web-app",
             "self-hosting/configuration",
             "self-hosting/reverse-proxy",
             "self-hosting/users",

src/content/docs/api/overview.md

@@ -5,7 +5,7 @@ description: Authentication, access, paging, errors, and caching in the Chek ser
 
 Chek server has a JSON API under `/api/v1`. The Chek app and the web app use it, and your own clients can too.
 
-[`openapi.yaml`](https://github.com/readchek/chek/blob/main/openapi.yaml) in the chek repository describes the API in OpenAPI 3.1. It's the contract: a change to the API changes that file in the same pull request. Each server release tags the version of the file that it implements. The [API reference](/api/reference/) on this site comes from the file at release 0.3.0. To generate a client, use the file at the tag that matches your server.
+[`openapi.yaml`](https://github.com/readchek/chek/blob/main/openapi.yaml) in the chek repository describes the API in OpenAPI 3.1. It's the contract: a change to the API changes that file in the same pull request. Each server release tags the version of the file that it implements. The [API reference](/api/reference/) on this site comes from the file at release 0.5.0. To generate a client, use the file at the tag that matches your server.
 
 ## Authentication
 
@@ -59,7 +59,7 @@ A library that a reader can't see answers `404`, and so do its series and public
 
 ## Browsers
 
-The API answers browser requests only from the origins in `CHEK_WEB_ORIGINS`. The default is `https://app.chek.page`. Requests carry a bearer token and never cookies. A page served over HTTPS can call only HTTPS servers.
+The API answers browser requests only from the origins in `CHEK_WEB_ORIGINS`. The default is `https://app.chek.page`. The web app that the server serves calls its own origin, so it needs no entry. Requests carry a bearer token and never cookies. A page served over HTTPS can call only HTTPS servers.
 
 ## Paging
 

src/content/docs/get-started/introduction.md

@@ -8,7 +8,7 @@ Chek is a reader for books and comics. It has five parts. You need only the part
 | Part | What it does | Repository |
 | --- | --- | --- |
 | Chek app | Reads books and comics on iPhone and iPad. It opens files on the device with no account, and it connects to Chek servers. It's free on the [App Store](https://apps.apple.com/us/app/chek-books-comics/id6761271144). | [readchek/app](https://github.com/readchek/app) |
-| Chek web app | Changes account and content settings at [app.chek.page](https://app.chek.page). It calls your server from the browser. | [readchek/app](https://github.com/readchek/app/tree/main/web) |
+| Chek web app | Reads your server's libraries in a browser, and runs the admin panel that sets up and manages a server. Your server serves it, and so does [app.chek.page](https://app.chek.page). | [readchek/app](https://github.com/readchek/app/tree/main/web) |
 | Chek server | Serves a library that you host yourself. It scans folders, reads Komga and Kavita servers, runs source extensions, syncs reading positions, and serves an OPDS 2 catalog. It's written in Rust. | [readchek/chek](https://github.com/readchek/chek) |
 | Extensions | Add sources that the server reads series from. Each extension is a WebAssembly component that the server installs from an extension repository. | [readchek/extensions](https://github.com/readchek/extensions) |
 | Chek Reader | Opens, lays out, and pages publications in the app. It's a Swift package with no Chek-specific code, so any Apple app can use it. | [readchek/chek-reader](https://github.com/readchek/chek-reader) |
@@ -20,6 +20,7 @@ The app reads files on the device without a server. A server adds three things.
 ## Pick your path
 
 - To run your own library server, start with the [quick start](/get-started/quick-start/). Then [install the server](/self-hosting/install/) behind HTTPS.
+- To read your server's libraries in a browser, read [Read in a browser](/self-hosting/web-app/).
 - To build a client, a script, or an integration, read the [API overview](/api/overview/) and the [API reference](/api/reference/).
 - To browse Chek from an OPDS reader, read [Browse Chek from an OPDS reader](/self-hosting/opds/).
 - To write a source, read the [extension README](https://github.com/readchek/chek/blob/main/extensions/README.md). It covers the `chek ext` command.

src/content/docs/get-started/quick-start.md

@@ -1,9 +1,9 @@
 ---
 title: Quick start
-description: Run Chek server in Docker on your computer, create the admin account, add a folder, and read it in the app.
+description: Run Chek server in Docker on your computer, set it up in the admin panel, add a folder, and read it in the browser and the app.
 ---
 
-In this tutorial, we run Chek server on your computer, add a folder of comics to it, and read that folder in the Chek app. It takes about ten minutes.
+In this tutorial, we run Chek server on your computer, add a folder of comics to it, and read that folder in the browser and in the Chek app. It takes about ten minutes.
 
 This setup is for trying Chek on your home network. Before other people use your server over the internet, follow [Install the server](/self-hosting/install/) and [Serve Chek over HTTPS](/self-hosting/reverse-proxy/).
 
@@ -46,42 +46,31 @@ Find the token in the log:
 docker logs chek
 ```
 
-Next, send the token with the name and password of the admin account. Replace the two values in angle brackets.
+Next, open `http://localhost:8080/admin` in a browser. The admin panel shows **Set up Chek**.
 
-```sh
-curl -X POST localhost:8080/api/v1/setup \
-	-H 'content-type: application/json' \
-	-d '{"setupToken": "<token from the log>", "name": "admin", "password": "<a long password>"}'
-```
-
-The response is a JSON object with a `token` field. Save the token in a shell variable, because the next steps use it:
+Paste the token into **Setup token**. Then fill in **Your name** and a password of 8 or more characters, and click **Create admin account**.
 
-```sh
-TOKEN=<the token from the response>
-```
+The admin panel signs you in and shows **Add a library**.
 
 ## Add your folder
 
-Now add the folder as a library. Use the path inside the container, `/library`, not the path on your computer.
+Now add the folder as a library. Under **Where your library is**, keep **A folder on this server**.
 
-```sh
-curl -X POST localhost:8080/api/v1/libraries \
-	-H "Authorization: Bearer $TOKEN" \
-	-H 'content-type: application/json' \
-	-d '{"name": "Comics", "path": "/library"}'
-```
+In **Folder**, enter `/library`. That is the path inside the container, not the path on your computer. You can also click **Browse** and choose the folder.
 
-The server starts to scan the folder at once. A large folder takes some minutes. To see how far the scan is, list the libraries:
+Type `Comics` in **Name**, and click **Add library**.
 
-```sh
-curl localhost:8080/api/v1/libraries -H "Authorization: Bearer $TOKEN"
-```
+The server starts to scan the folder at once. The library's page shows the scan under **Scan**. Books show up as the server finds them, and a large folder takes some minutes.
+
+## Read in the browser
+
+Open `http://localhost:8080/` in a new tab. This is the Chek web app, and the server serves it too.
 
-Each library in the response has a `scan` field with the state of its scan.
+Sign in with the name and password of the admin account. Then click **Shared**, and open the **Comics** library. Click a comic to read it.
 
 ## Read in the app
 
-Finally, open the Chek app on a device on the same network. Add a server with your computer's address and port, such as `192.168.1.20:8080`, and sign in as `admin`. Your comics appear in the app.
+Finally, open the Chek app on an iPhone or iPad on the same network. Add a server with your computer's address and port, such as `192.168.1.20:8080`, and sign in as the admin. Your comics appear in the app.
 
 The app uses plain HTTP only for addresses on your local network. For any other address, the server needs HTTPS.
 

src/content/docs/self-hosting/configuration.md

@@ -13,6 +13,7 @@ Chek server reads its settings from environment variables only. Every variable i
 | `CHEK_DATA_DIR` | `./data`. In the image, `/data` | The folder for the database, covers, and extensions |
 | `CHEK_SCAN_WORKERS` | One less than the number of cores | The number of files that a scan reads at once |
 | `CHEK_SETUP_TOKEN` | A random token, written to the log | The token that creates the first admin account. It must be 32 or more characters |
+| `CHEK_WEB_DIR` | None. In the image, `/usr/share/chek/web` | The folder with the [web app's](/self-hosting/web-app/) build. The server serves it at `/`, with the admin panel at `/admin`. `CHEK_ADMIN_DIR` is its old name and still works |
 | `CHEK_MAX_UPLOAD_BYTES` | `2147483648`, which is 2 GiB | The largest file that an admin can upload |
 
 ## Proxies and browsers
@@ -21,7 +22,7 @@ Chek server reads its settings from environment variables only. Every variable i
 | --- | --- | --- |
 | `CHEK_TRUSTED_PROXIES` | None | Comma-separated addresses or CIDR ranges of your reverse proxies, such as `10.0.0.0/8`. The server reads the client address from `X-Forwarded-For` only on requests from these addresses |
 | `CHEK_CLIENT_IP_HEADER` | None | A header to read the client address from, such as `CF-Connecting-IP`. The server reads it only on requests from `CHEK_TRUSTED_PROXIES` |
-| `CHEK_WEB_ORIGINS` | `https://app.chek.page` | Comma-separated origins that may call the API from a browser |
+| `CHEK_WEB_ORIGINS` | `https://app.chek.page` | Comma-separated origins that may call the API from a browser. The web app that the server serves needs no entry |
 
 ## Sign-in
 

src/content/docs/self-hosting/extensions.md

@@ -7,7 +7,7 @@ An extension is a source that the server reads series from, such as a webcomic's
 
 This page is about running extensions on your server. To write one, read the [extension README](https://github.com/readchek/chek/blob/main/extensions/README.md).
 
-Most people manage repositories and installs in the Chek app, so they never call the endpoints on this page.
+Most people manage repositories and installs in the Chek app, so they never call the endpoints on this page. Admins manage server-wide repositories in the admin panel, under **Extensions**.
 
 ## Add an extension repository
 
@@ -16,7 +16,7 @@ A repository is an `index.json` file and the components that it lists, served ov
 - A server-wide repository belongs to the admins, and every user sees it. A new server starts with the official repository, `https://chek.page/extensions/index.json`. An admin can remove it.
 - A personal repository belongs to one user, and only that user sees it.
 
-By default, only admins can add repositories. To let every user add personal repositories, turn on `allowAnyRepository`:
+By default, only admins can add repositories. To let every user add personal repositories, turn on **Let people add any repository** under **Extensions** in the admin panel. With the API, turn on `allowAnyRepository`:
 
 ```sh
 curl -X PUT $SERVER/api/v1/settings \

src/content/docs/self-hosting/first-steps.md

@@ -1,19 +1,74 @@
 ---
 title: Set up a new server
-description: Create the admin account, add libraries, and create accounts for other people.
+description: Create the admin account, add libraries, and create accounts for other people in the admin panel or with the API.
 ---
 
-The app doesn't manage libraries or accounts yet, so you do these steps with `curl`. After setup, every request sends the admin's session token in an `Authorization: Bearer <token>` header.
+The server serves an admin panel at `/admin`. It sets up a new server and manages its libraries, people, and extension repositories. The Docker image includes it. To set up without a browser, use the API instead, as [Set up with the API](#set-up-with-the-api) describes.
+
+## Open the admin panel
+
+Open `http://<your server>:8080/admin` in a browser. Behind a reverse proxy, open `https://<your domain>/admin`.
+
+If the server has an HTTPS address, you can also manage it from [app.chek.page/admin](https://app.chek.page/admin). Enter the server's address in **Server address**.
+
+## Create the admin account
+
+A server with no accounts shows **Set up Chek**.
+
+1. In **Setup token**, enter the token. If you set `CHEK_SETUP_TOKEN`, use that value. If you didn't, find the one-time token in the log with `docker logs chek`.
+2. Fill in **Your name**, **Password**, and **Password again**. The password needs 8 or more characters.
+3. Click **Create admin account**.
+
+The admin panel signs you in and opens **Add a library**. After the first admin exists, the admin panel asks for a name and password instead.
+
+## Add a folder library
+
+1. Under **Where your library is**, choose **A folder on this server**.
+2. In **Folder**, enter the folder's path inside the container, such as `/library/books`. To choose the folder from a list, click **Browse**.
+3. In **Name**, enter the name that readers see.
+4. Click **Add library**.
+
+The server starts the first scan at once. It also scans every folder library each time it starts. That scan skips files whose size and modification time haven't changed. To pick up changes while the server runs, open the library in **Libraries** and click **Scan now**.
+
+A library can also read a [Komga or Kavita server](/self-hosting/komga-and-kavita/) or run an [extension](/self-hosting/extensions/#turn-an-extension-into-a-library).
+
+## Create accounts for other people
+
+An account is an admin or a reader. A reader sees only the libraries that you choose for it.
+
+1. Open **People**, and click **Add person**.
+2. Enter the person's **Name** and **Password**.
+3. Under **Role**, choose **Reader** or **Admin**.
+4. For a reader, choose the libraries under **Libraries they can read**.
+5. Click **Add person**.
+
+To change an account's role, password, or libraries, open the account in **People**. For the rules on roles, sessions, and sign-in limits, read [Accounts and access](/self-hosting/users/).
+
+## Rename or delete a library
+
+Open the library in **Libraries**.
+
+- To rename it, change the name under **Name** and click **Rename**.
+- To delete it, click **Delete library**. Deleting a library deletes everyone's progress, bookmarks, and highlights in it. The files stay in the folder, and the books stay on Komga or Kavita. You can't delete a library while the server scans it.
+
+## Connect a client
+
+- In a browser, open the server's address. The server serves the Chek web app at `/`. Read [Read in a browser](/self-hosting/web-app/).
+- In the Chek app, add the server's address and sign in. The app reads your libraries, syncs your place, and manages extension repositories and installs.
+- In an OPDS reader, follow [Browse Chek from an OPDS reader](/self-hosting/opds/).
+- In your own code, start with the [API overview](/api/overview/).
+
+## Set up with the API
+
+Every step in the admin panel has an endpoint. After setup, every request sends the admin's session token in an `Authorization: Bearer <token>` header.
 
 Set the server's address in a shell variable first:
 
 ```sh
 SERVER=https://chek.example.org
 ```
 
-## Create the admin account
-
-A server with no accounts accepts one setup request. If you set `CHEK_SETUP_TOKEN`, use that value as the token. If you didn't, find the one-time token in the log with `docker logs chek`.
+A server with no accounts accepts one setup request. Send the setup token with the admin's name and password:
 
 ```sh
 curl -X POST $SERVER/api/v1/setup \
@@ -29,8 +84,6 @@ TOKEN=<the token from the response>
 
 After the first admin exists, setup answers `409 already_set_up`. To get a new token later, sign in with `POST /api/v1/auth/sign-in` and the same name and password.
 
-## Add a folder library
-
 To add a folder, give its path inside the container:
 
 ```sh
@@ -39,30 +92,14 @@ curl -X POST $SERVER/api/v1/libraries \
 	-d '{"name": "Books", "path": "/library/books"}'
 ```
 
-The server starts the first scan at once. It also scans every folder library each time it starts. That scan skips files whose size and modification time haven't changed.
-
-To pick up changes while the server runs, start a scan:
-
-```sh
-curl -X POST $SERVER/api/v1/libraries/1/scan -H "Authorization: Bearer $TOKEN"
-```
-
-A library can also read a [Komga or Kavita server](/self-hosting/komga-and-kavita/) or run an [extension](/self-hosting/extensions/#turn-an-extension-into-a-library).
-
-## Create accounts for other people
+To scan a library again, send `POST /api/v1/libraries/{libraryId}/scan`. To rename it, send `PATCH /api/v1/libraries/{libraryId}`. To delete it, send `DELETE /api/v1/libraries/{libraryId}`.
 
-An account is an admin or a reader. A reader sees only the libraries in its `libraryIds`.
+To create an account, send its name, password, role, and the ids of the libraries that a reader may see:
 
 ```sh
 curl -X POST $SERVER/api/v1/users \
 	-H "Authorization: Bearer $TOKEN" -H 'content-type: application/json' \
 	-d '{"name": "sam", "password": "<8 or more characters>", "role": "reader", "libraryIds": [1, 2]}'
 ```
 
-To change an account's role, password, or libraries, send `PATCH /api/v1/users/{userId}`. For the rules on roles, sessions, and sign-in limits, read [Accounts and access](/self-hosting/users/).
-
-## Connect a client
-
-- In the Chek app, add the server's address and sign in. The app reads your libraries, syncs your place, and manages extension repositories and installs.
-- In an OPDS reader, follow [Browse Chek from an OPDS reader](/self-hosting/opds/).
-- In your own code, start with the [API overview](/api/overview/).
+To change an account's role, password, or libraries, send `PATCH /api/v1/users/{userId}`.

src/content/docs/self-hosting/install.md

@@ -12,7 +12,8 @@ CI publishes the image `ghcr.io/readchek/chek` for amd64 and arm64.
 | Tag | Contents |
 | --- | --- |
 | `latest` | The newest release |
-| A version, such as `0.3.0` | That release |
+| A version, such as `0.5.0` | That release |
+| A minor series, such as `0.5` | The newest release in that series |
 | `edge` | The newest commit on `main` |
 | Any tag above with `-browser` added, such as `latest-browser` | The same server with Chromium, for extensions that need a browser |
 
@@ -77,9 +78,9 @@ The chek repository has a Compose file for Dokploy at [`deploy/server/compose.ya
 
 1. Create a Compose application from `readchek/chek`, and select `deploy/server/compose.yaml`.
 2. In **Environment**, set `CHEK_SETUP_TOKEN` to 32 or more random characters.
-3. To run a release instead of `main`, also set `CHEK_IMAGE`, such as `ghcr.io/readchek/chek:0.3.0-browser`.
+3. To run a release instead of `main`, also set `CHEK_IMAGE`, such as `ghcr.io/readchek/chek:0.5.0-browser`.
 4. Route your domain to the service `chek` on port `8080`, with HTTPS.
-5. Deploy, then [create the admin account](/self-hosting/first-steps/#create-the-admin-account).
+5. Deploy, then open `/admin` on your domain and [create the admin account](/self-hosting/first-steps/#create-the-admin-account).
 
 The Compose file mounts no folders of books. To read files from the host, add a read-only bind mount, such as `/srv/books:/library/books:ro`.
 

src/content/docs/self-hosting/komga-and-kavita.md

@@ -7,6 +7,8 @@ An admin can add a [Komga](https://komga.org) or [Kavita](https://www.kavitaread
 
 Create an account in Komga or Kavita for Chek to use. Chek checks the credentials before it adds the library. It stores them on the server and never returns them from the API.
 
+To add the library in the admin panel, open **Libraries** and click **Add library**. Then choose **A Komga server** or **A Kavita server**, and fill in the same details that the steps below send to the API.
+
 ## Add a Komga library
 
 The Komga account needs the page streaming role and the file download role.