docs: docs tentatively finished

DEV.md

@@ -1,14 +0,0 @@
-# Koito
-## Dependencies
-### libvips
-```
-sudo apt install libvips
-```
-## Tools
-- goose
-- sqlc
-## Start dev env
-```
-make postgres.run
-make api.debug
-```

FEATURES.md

@@ -1,24 +0,0 @@
-# Must-haves
-- scrobble with listenbrainz api
-- import from maloja
-- import from spotify
-- natively host on subdirectory
-- good mobile ui
-- replace artist/album/track art from ui
-- fetch artist/album/track art from lastfm and/or spotify
-- edit artist/album/track name in ui (auto-merge colliding names)
-- built with being exposed to the internet in mind
-- track artist aliases
-- hold a cache of musicbrainz responses, with a button to clear it out
-# Want
-- use musibrainz ids from scrobble to automatically merge plays
-- use musicbrainz ids from scrobble to automatically add AKA fields (美波 aka Minami) and sort name
-- export playlist m3u8 files based on charts
-- track device/player listened from
-- webhooks on certain events (every scrobble, listening milestones, etc.)
-- Time of day, day of week, etc. graphs
-- "pause" mode that temporarily disables recieving scrobbles until turned back on
-# Stretch
-- "Listening Digest" wrapped-esque digestable recap of the last week/month/year
-# Could explore
-- Federation/ActivityPub

docs/astro.config.mjs

@@ -8,19 +8,24 @@ import tailwindcss from '@tailwindcss/vite';
 export default defineConfig({
   integrations: [
       starlight({
-          title: 'Koito Docs',
+          title: 'Koito',
           social: [{ icon: 'github', label: 'GitHub', href: 'https://github.com/gabehf/koito' }],
           sidebar: [
               {
                   label: 'Guides',
                   items: [
                       // Each item here is one entry in the navigation menu.
-                      { label: 'Example Guide', slug: 'guides/example' },
+                      { label: 'Installation', slug: 'guides/installation' },
+                      { label: 'Importing Data', slug: 'guides/importing' },
+                      { label: 'Setting up the Scrobbler', slug: 'guides/scrobbler' },
+                      { label: 'Editing Data', slug: 'guides/editing' },
                   ],
               },
               {
                   label: 'Reference',
-                  autogenerate: { directory: 'reference' },
+                  items: [
+                    { label: 'Configuration Options', slug: 'reference/configuration' },
+                  ]
               },
           ],
 		  customCss: [

docs/src/content/docs/guides/editing.md

@@ -0,0 +1,66 @@
+---
+title: Editing Data
+description: How to edit artist, album, and track information in your Koito instance.
+---
+
+In order to start editing information on your Koito instance, you need to be logged in. See the [Setting up the Scrobber](/guides/scrobbler) guide if you need to log in for the first time.
+
+Once logged in, navigate to the page of the item you want to edit. For this example, we will use the fantastic Korean dream pop group [OurR](https://www.youtube.com/watch?v=USHrBJRmF-o).
+When you are logged in and on an artist, album, or track page, you will see the editing options on the top right.
+
+![A Koito page for the band OurR, showing the editing options](../../../assets/ourr.png)
+
+#### Editing Aliases
+
+The first option from the left is the Alias Manager. This is the option that lets us add known aliases for artists, albums, and tracks. Here, we can see that one alias
+has already been filled in from MusicBrainz.
+
+![a menu showing current aliases, with editing options](../../../assets/alias_manager.png)
+
+In the alias manager, we have three options: adding an alias, setting an alias as primary, and deleting an alias.
+
+To add an alias, fill in the alias you want to add into the input. Then, click "submit". You will see the new alias appear in the list.
+
+To set an alias as primary, click the "Set Primary" option next to the alias. Doing so will set that as the alias you see in the UI for the artist, album, or track.
+
+To delete an alias, just click on the delete button.
+
+Koito uses aliases for not only the UI, but also for matching artists, albums, and tracks submitted to the scrobbler, and for searching. So if you are like me and listen to a lot of
+music from countries with non-latin script, adding aliases makes it easy to search for those items.
+
+:::note
+Koito uses MusicBrainz IDs to find additional aliases for artists and albums, if your music server provides them. Additional track aliases have to be added manually.
+:::
+
+#### Editing Images
+
+The easiest way to replace an image is to simply drag an image file from your computer onto the page of the artist, album, or track you want to change the image for. This only works when you are logged in.
+
+The other way to replace images is using the Replace Image option, which is the second editing option in the list. Here we will use OurR's 2021 single 잠.
+
+![a menu with an option to link an image, or click on a suggested album cover](../../../assets/replace_image.png)
+
+Opening the Replace Image menu, we can either provide a link to the image we want to use, or, in this case, we can see a suggested image is provided. The image suggestions are provided by
+Cover Art Archive, and only work for albums that have an associated MusicBrainz ID. Koito gets these IDs from your scrobbler, if its provides them. If not, you can always use a local image or provide a link.
+
+#### Merging Items
+
+Koito allows you to merge two items, which means that all of that item's children (for artists: albums, tracks and listens; for albums: tracks and listens; etc.) will be assigned to
+a different item, and the old item will be removed.
+
+For this example, we will use the incredible track [Tsumugu](https://www.youtube.com/watch?v=NDwqZIXOvKw) by the Japanese artist とた (Tota). Here we can see there two versions of the track,
+one in Japanese and one romanized. I only want to keep the Japanese one. So, just navigate to the page for the Japanese-titled track, open the Merge Items menu (the third editing option), search for
+the track we want to be merged, and click "Merge Items". A text will appear in the UI to clarify which track is the primary and which will be merged into it.
+
+![a menu preparing for the track Tsumugu to be merged into 紡ぐ](../../../assets/merge.png)
+
+If we wanted to merge the other way, and only keep the romanized track, just click the "Reverse merge order" checkbox.
+
+Once merged, we can see that all of the listen activity for Tsumugu has been asigned to 紡ぐ.
+
+![an activity heatmap showing more listens than were previously there](../../../assets/merged_activity.png)
+
+#### Deleting Items
+
+To delete at item, just click the trash icon, which is the fourth and final icon in the editing options. Doing so will open a confirmation dialogue. Once confirmed, the item you delete, as well as all of its children
+and listen activity, will be removed.

docs/src/content/docs/guides/example.md

@@ -1,11 +0,0 @@
----
-title: Example Guide
-description: A guide in my new Starlight docs site.
----
-
-Guides lead a user through a specific task they want to accomplish, often with a sequence of steps.
-Writing a good guide requires thinking about what your users are trying to do.
-
-## Further reading
-
-- Read [about how-to guides](https://diataxis.fr/how-to-guides/) in the Diátaxis framework

docs/src/content/docs/guides/importing.md

@@ -0,0 +1,28 @@
+---
+title: Importing Data
+description: How to import your existing listening history from other services into Koito.
+---
+
+Koito currently supports two sources to import data from: **Spotify** and **Maloja**.
+
+## Spotify
+
+To get your data from Spotify, you first need to request your extended streaming history from [the Spotify privacy page](https://www.spotify.com/us/account/privacy/). 
+The export could take up to 30 days, according to Spotify. Then, all you have to do is put the `.json` files from your data export into the
+`import` folder in your config directory, and restart Koito. The data import will then start automatically.
+
+Koito relies on file names to find files to import. If the files aren't being imported automatically, make sure they contain `Streaming_History_Audio` in the file name.
+
+![The Spotify data export page](../../../assets/spotify_export.png)
+
+## Maloja
+
+You can download your data from Maloja by clicking the `Export` button under Download Data on the `/admin_overview` page of your Maloja instance. Then,
+put the resuling `.json` file into the `import` folder in your config directory, and restart Koito. The data import will then start automatically.
+
+Koito relies on file names to find files to import. If the files aren't being imported automatically, make sure they contain `maloja` in the file name.
+
+:::note
+Maloja may have missing or inconsistent track duration information, which means that the 'Hours Listened' statistic may be incorrect after a Maloja import. However, track
+durations will be filled in as you submit listens using the API.
+:::

docs/src/content/docs/guides/installation.md

@@ -0,0 +1,105 @@
+---
+title: Installation
+description: Guide on how to install Koito to start tracking your listening history.
+---
+
+## Docker
+By far the easiest way to get up and running with Koito is using docker. Here is an example Docker Compose file to get you up and running in minutes:
+```yaml title="compose.yaml"
+services:
+  koito:
+    image: gabehf/koito:latest
+    container_name: koito
+    depends_on:
+      - db
+    user: 1000:1000
+    environment:
+      - KOITO_DATABASE_URL=postgres://postgres:secret_password@db:5432/koitodb
+      - KOITO_ALLOWED_HOSTS=koito.example.com,192.168.0.100
+    ports:
+      - "4110:4110"
+    volumes:
+      - ./koito-data:/etc/koito
+    restart: unless-stopped
+
+  db:
+    image: postgres:16
+    container_name: psql
+    restart: unless-stopped
+    environment:
+      POSTGRES_DB: koitodb
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: secret_password
+    volumes:
+      - ./db-data:/var/lib/postgresql/data
+
+```
+Or, you can use `docker run` commands. First, you need to run Postgres:
+```sh
+docker run \
+    --name psql \
+    --restart unless-stopped \
+    -e POSTGRES_DB=koitodb \
+    -e POSTGRES_USER=postgres \
+    -e POSTGRES_PASSWORD=secret_password \
+    -v ./db-data:/var/lib/postgresql/data \
+    -p 5432:5432 \
+    -d \
+    postgres:16
+```
+Then, run Koito:
+```sh
+docker run \
+    --name koito \
+    -u 1000:1000 \
+    -e KOITO_DATABASE_URL=postgres://postgres:secret_password@postgres_ip:5432/koitodb \
+    -e KOITO_ALLOWED_HOSTS=koito.example.com,192.168.0.100 \
+    -p 4110:4110 \
+    -v ./koito-data:/etc/koito \
+    --restart unless-stopped \
+    -d \
+    gabehf/koito:latest
+```
+Be sure to replace `secret_password` with a random password of your choice, and set `KOITO_ALLOWED_HOSTS` to include the domain name or IP address you will be accessing Koito 
+from when using either of the Docker methods described above.
+
+Those are the two required environment variables. You can find a full list of configuration options in the [configuration reference](/reference/configuration).
+
+When using `docker run`, you will also need to fill in the IP address of your postgres instance.
+
+:::caution
+Setting `KOITO_ALLOWED_HOSTS=*` will allow requests from any host, but this is not recommended as it introduces security vulnerabilities.
+:::
+
+## Build from source
+
+If you don't want to use docker, you can also build the application from source.
+
+First, you need to install dependencies. Koito relies on `libvips-dev` to process images.
+
+```sh
+sudo apt install libvips-dev
+```
+
+If you aren't installing on an Ubuntu or Debian based system, you can find other ways to install `libvips-dev` on the [libvips wiki](https://github.com/libvips/libvips/wiki/)
+
+Then, clone the repository and execute the build command using the included Makefile:
+
+```sh
+git clone https://github.com/gabehf/koito && cd koito
+make build
+```
+
+When the build is finished, you can run the executable at the root of the directory. You'll also need to defined the required environment variables.
+
+```sh
+KOITO_DATABASE_URL=postgres://postgres:secret_password@postgres_ip:5432/koitodb \
+KOITO_ALLOWED_HOSTS=koito.example.com,192.168.0.100 \
+./koito
+```
+
+Then, navigate your browser to `localhost:4110` to enter your Koito instance.
+
+:::note
+You will need to provide your own Postgres instance. You can find downloads to Postgres [here](https://www.postgresql.org/download/).
+:::

docs/src/content/docs/guides/scrobbler.md

@@ -0,0 +1,35 @@
+---
+title: Setting up the Scrobber
+description: How to relay listens submitted to Koito to another ListenBrainz compatible server.
+---
+
+To use the ListenBrainz API, you need to get your generated api key from the UI.
+
+First, open the settings in your Koito instance by clicking on the settings icon or pressing `\`.
+
+Then, you can navigate to the account tab and log in using the default credentials `admin` and `changeme`, or
+the credentials you supplied when first running Koito using the `KOITO_DEFAULT_USERNAME` and `KOITO_DEFAULT_PASSWORD` environment variables.
+
+:::caution
+Be sure to change the username and password after logging in for the first time if you used the defaults.
+:::
+
+After logging in, open the settings menu again and find the `API Keys` tab. On this tab, you will find the automatically generated API key.
+
+:::note
+If you are not running Koito on an `https://` connection or `localhost`,  the click-to-copy button will not work. Instead, just click on the key itself to highlight and copy it.
+:::
+
+Then, direct any application you want to scrobble data from to `{your_koito_address}/apis/listenbrainz/1` and provide the api key from the UI as the token.
+
+## Set up a relay
+
+Koito allows you to relay listens submitted via the ListenBrainz-compatible API to another ListenBrainz-compatible server.
+In order to use this feature, all you need to do is set the `KOITO_ENABLE_LBZ_RELAY`, `KOITO_LBZ_RELAY_URL`, and `KOITO_LBZ_RELAY_TOKEN` variables in your environment.
+After setting these variables, be sure to restart your Koito instance to apply the settings.
+
+Once the relay is configured, Koito will automatically forward any requests it recieves on `/apis/listenbrainz/1` to the URL provided in the configuration.
+
+:::note
+Be sure to include the full path to the ListenBrainz endpoint of the server you are relaying to in the `KOITO_LBZ_RELAY_URL`.
+:::

docs/src/content/docs/index.mdx

@@ -1,36 +1,36 @@
 ---
-title: Home
-description: Get started building your docs site with Starlight.
+title: The modern, open source scrobbler
+description: Visualize your listening history with a modern, open source, ListenBrainz-compatible scrobbler.
 template: splash
 hero:
-  tagline: Congrats on setting up a new Starlight project!
+  tagline: Explore your listening patterns, track your favorite artists, and relay scrobbles to other sites — all from a fast, themeable server that you control.
   image:
-    file: ../../assets/houston.webp
+    file: ../../assets/out.webp
   actions:
-    - text: Example Guide
-      link: /guides/example/
+    - text: Get Started
+      link: /guides/installation/
       icon: right-arrow
-    - text: Read the Starlight docs
-      link: https://starlight.astro.build
+    - text: View a live instance
+      link: https://koito.mnrva.dev
       icon: external
       variant: minimal
 ---
 
 import { Card, CardGrid } from '@astrojs/starlight/components';
 
-## Next steps
+## Features
 
 <CardGrid>
-	<Card title="Update content" icon="pencil">
-		Edit `src/content/docs/index.mdx` to see this page change.
+	<Card title="ListenBrainz compatible" icon="puzzle">
+		Koito can be connected to any music server or client that allows for custom ListenBrainz URLs.
 	</Card>
-	<Card title="Add new content" icon="add-document">
-		Add Markdown or MDX files to `src/content/docs` to create new pages.
+	<Card title="Scrobbler relay" icon="rocket">
+		Automatically relay listens submitted to your Koito instance to other ListenBrainz compatble servers.
 	</Card>
-	<Card title="Configure your site" icon="setting">
-		Edit your `sidebar` and other config in `astro.config.mjs`.
+	<Card title="Automatic data fetching" icon="download">
+		Koito automatically fetches data from MusicBrainz and images from Deezer and Cover Art Archive to compliment what is provided by your music server.
 	</Card>
-	<Card title="Read the docs" icon="open-book">
-		Learn more in [the Starlight Docs](https://starlight.astro.build/).
+	<Card title="Themeable" icon="seti:css">
+		Koito ships with twelve different themes, with custom theme options to be added soon™.
 	</Card>
 </CardGrid>

docs/src/content/docs/reference/configuration.md

@@ -0,0 +1,64 @@
+---
+title: Configuration
+description: The available configuration options when setting up Koito.
+---
+
+Koito is configured using **environment variables**. This is the full list of configuration options supported by Koito.
+
+##### KOITO_DATABASE_URL
+- Required: `true`
+- Description: A Postgres connection URI. See https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING-URIS for more information.
+##### KOITO_ALLOWED_HOSTS
+- Required: `true`
+- Description: A list of hosts to allow requests from. E.g. `koito.mydomain.com,192.168.0.100`.
+##### KOITO_DEFAULT_USERNAME
+- Default: `admin`
+- Description: The username for the user that is created on first startup. Only applies when running Koito for the first time.
+##### KOITO_DEFAULT_PASSWORD 
+- Default: `changeme`
+- Description: The password for the user that is created on first startup. Only applies when running Koito for the first time.
+##### KOITO_BIND_ADDR
+- Description: The address to bind to. The default blank value is equivalent to `0.0.0.0`.
+##### KOITO_LISTEN_PORT
+- Default: `:4110`
+- Description: The port Koito will listen on.
+##### KOITO_ENABLE_STRUCTURED_LOGGING
+- Description: When set to `true`, will log in JSON format.
+##### KOITO_ENABLE_FULL_IMAGE_CACHE
+- Default: `false`
+- Description: When set to `true`, will store the full size downloaded images, which can then be served under `/images/full`.
+##### KOITO_LOG_LEVEL
+- Default: `info`
+- Description: One of `debug | info | warn | error | fatal`
+##### KOITO_MUSICBRAINZ_URL
+- Default: `https://musicbrainz.org`
+- Description: The URL Koito will use to contact MusicBrainz. Replace this value if you have your own MusicBrainz mirror.
+##### KOITO_ENABLE_LBZ_RELAY
+- Default: `false`
+- Description: Set to `true` if you want to relay requests from the ListenBrainz endpoints on your Koito server to another ListenBrainz compatible server.
+##### KOITO_LBZ_RELAY_URL
+- Required: `true` if relays are enabled.
+- Description: The URL to which relayed requests will be sent to.    
+##### KOITO_LBZ_RELAY_TOKEN
+- Required: `true` if relays are enabled. 
+- Description: The user token to send with the relayed ListenBrainz requests.
+##### KOITO_CONFIG_DIR
+- Default: `/etc/koito`
+- Description: The location where import folders and image caches are stored.
+##### KOITO_DISABLE_DEEZER 
+- Default: `false`
+- Description: Disables Deezer as a source for finding artist and album images.
+##### KOITO_DISABLE_COVER_ART_ARCHIVE 
+- Default: `false`
+- Description: Disables Cover Art Archive as a source for finding album images.
+##### KOITO_DISABLE_MUSICBRAINZ
+- Default: `false`
+##### KOITO_SKIP_IMPORT
+- Default: `false`
+- Description: Skips running the importer on startup.
+##### KOITO_DISABLE_RATE_LIMIT
+- Default: `false`
+- Description: When enabled, disables the rate limiter that Koito has on the `/apis/web/v1/login` endpoint.
+##### KOITO_THROTTLE_IMPORTS_MS
+- Default: `0`
+- Description: The amount of time to wait, in milliseconds, between listen imports. Can help when running Koito on low-powered machines.