From aa21a8198080d4f2e5a3028c0c5a4634fe087004 Mon Sep 17 00:00:00 2001 From: Gabe Farrell Date: Fri, 13 Jun 2025 00:53:00 -0400 Subject: [PATCH] docs: update docs --- .github/workflows/docs.yml | 39 +++++++++++++++++++ docs/src/content/docs/guides/importing.md | 27 ++++++++++++- docs/src/content/docs/guides/installation.md | 38 +++--------------- .../content/docs/reference/configuration.md | 3 ++ docs/src/content/docs/reference/example.md | 11 ------ 5 files changed, 73 insertions(+), 45 deletions(-) create mode 100644 .github/workflows/docs.yml delete mode 100644 docs/src/content/docs/reference/example.md diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..cc077cc --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,39 @@ +name: Deploy docs to GitHub Pages + +on: + # Trigger the workflow every time you push to the `main` branch + # Using a different branch name? Replace `main` with your branch’s name + push: + branches: [main] + # Allows you to run this workflow manually from the Actions tab on GitHub. + workflow_dispatch: + +# Allow this job to clone the repo and create a page deployment +permissions: + contents: read + pages: write + id-token: write + +jobs: + build: + runs-on: ubuntu-latest + steps: + - name: Checkout your repository using git + uses: actions/checkout@v4 + - name: Install, build, and upload your site output + uses: withastro/action@v4 + with: + path: ./docs # The root location of your Astro project inside the repository. (optional) + # node-version: 22 # The specific version of Node that should be used to build your site. Defaults to 22. (optional) + package-manager: yarn@latest # The Node package manager that should be used to install dependencies and build your site. Automatically detected based on your lockfile. (optional) + + deploy: + needs: build + runs-on: ubuntu-latest + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 \ No newline at end of file diff --git a/docs/src/content/docs/guides/importing.md b/docs/src/content/docs/guides/importing.md index 2e27bcf..26cfb3f 100644 --- a/docs/src/content/docs/guides/importing.md +++ b/docs/src/content/docs/guides/importing.md @@ -3,7 +3,20 @@ 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**. +Koito currently supports the following sources to import data from: +- Spotify +- Maloja +- LastFM (using https://lastfm.ghan.nl/export/) +- ListenBrainz + +:::note +ListenBrainz and LastFM imports can take a long time for large imports due to MusicBrainz requests being throttled at one per second. If you want +these imports to go faster, you can [disable MusicBrainz](/reference/configuration/#koito_disable_musicbrainz) in the config while running the importer. However, this +means that artist aliases will not be automatically fetched for imported artists. This also means that artists will not be associated with their MusicBrainz IDs internally, +which can lead to some artist matching issues, especially for people who listen to lots of foreign music. You can also use +[your own MusicBrainz mirror](https://musicbrainz.org/doc/MusicBrainz_Server/Setup) and +[disable MusicBrainz rate limiting](/reference/configuration/#koito_musicbrainz_url) in the config if you want imports to be faster. +::: ## Spotify @@ -25,4 +38,14 @@ Koito relies on file names to find files to import. If the files aren't being im :::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. -::: \ No newline at end of file +::: + +## LastFM + +First, create an export file using [this tool from ghan.nl](https://lastfm.ghan.nl/export/) in JSON format. Then, place the resulting file into the `import` folder in your config directory. +Once you restart Koito, it will automatically detect the file as a Last FM import, and begin adding your listen activity immediately. + +## ListenBrainz + +Create a ListenBrainz export file using [the export tool on the ListenBrainz website](https://listenbrainz.org/settings/export/). Then, place the resulting `.zip` file into the `import` +folder in your config directory. Once you restart Koito, your ListenBrainz activity will immediately start being imported. \ No newline at end of file diff --git a/docs/src/content/docs/guides/installation.md b/docs/src/content/docs/guides/installation.md index 84332d8..2fcbc36 100644 --- a/docs/src/content/docs/guides/installation.md +++ b/docs/src/content/docs/guides/installation.md @@ -12,7 +12,6 @@ services: 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 @@ -34,39 +33,12 @@ services: - ./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. ::: @@ -75,13 +47,15 @@ Setting `KOITO_ALLOWED_HOSTS=*` will allow requests from any host, but this is n 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. +First, you need to install dependencies. Koito relies on `make`, `yarn` for building the client, and `libvips-dev` to process images. ```sh -sudo apt install libvips-dev +sudo apt install libvips-dev make npm +sudo npm install --global yarn ``` -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/) +If you aren't installing on an Ubuntu or Debian based system, you can easily find ways to install make, npm, and yarn by googling, and +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: diff --git a/docs/src/content/docs/reference/configuration.md b/docs/src/content/docs/reference/configuration.md index f20e503..4c24512 100644 --- a/docs/src/content/docs/reference/configuration.md +++ b/docs/src/content/docs/reference/configuration.md @@ -33,6 +33,9 @@ Koito is configured using **environment variables**. This is the full list of co ##### 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_MUSICBRAINZ_RATE_LIMIT +- Default: `1` +- Description: The number of requests to send to the MusicBrainz server per second. Unless you are using your own MusicBrainz mirror, __do not touch this value__. ##### 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. diff --git a/docs/src/content/docs/reference/example.md b/docs/src/content/docs/reference/example.md deleted file mode 100644 index 0224f09..0000000 --- a/docs/src/content/docs/reference/example.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: Example Reference -description: A reference page in my new Starlight docs site. ---- - -Reference pages are ideal for outlining how things work in terse and clear terms. -Less concerned with telling a story or addressing a specific use case, they should give a comprehensive outline of what you're documenting. - -## Further reading - -- Read [about reference](https://diataxis.fr/reference/) in the Diátaxis framework