docs (#944)

lavalink-devs · Dec 2, 2023 · 86348bd · 86348bd
1 parent b78a956
commit 86348bd
Show file tree

Hide file tree

Showing 39 changed files with 2,503 additions and 1,311 deletions.
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
@@ -3,7 +3,11 @@ name: Build
 on:
   push:
     branches: [ '**' ]
-    paths-ignore: [ '**.md' ]
+    paths-ignore:
+      - '**.md'
+      - 'docs/**'
+      - '.github/workflows/docs.yml'
+      - '.github/workflows/docs-pr.yml'
   workflow_call:
     secrets:
       DOCKER_USERNAME:

diff --git a/.github/workflows/docs-pr.yml b/.github/workflows/docs-pr.yml
@@ -0,0 +1,49 @@
+name: Docs PR
+
+on:
+  pull_request_target:
+    branches: [ '**' ]
+    paths:
+      - 'docs/**'
+
+concurrency:
+    group: pages
+    cancel-in-progress: true
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      deployments: write
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          ref: "${{ github.event.pull_request.merge_commit_sha }}"
+          fetch-depth: 0
+      - uses: actions/setup-python@v4
+        with:
+          python-version: 3.x
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
+      - uses: actions/cache@v3
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+      - run: pip install -r requirements.txt
+        working-directory: docs
+#      - run: mkdocs build --verbose --strict
+      - run: mkdocs build --verbose
+        working-directory: docs
+      - uses: actions/upload-pages-artifact@v1
+        with:
+          path: 'site'
+      - uses: cloudflare/pages-action@v1
+        with:
+          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+          projectName: ${{ vars.CLOUDFLARE_PROJECT_NAME }}
+          directory: site
+          branch: pr-${{ github.event.pull_request.number }}
+          gitHubToken: ${{ secrets.GITHUB_TOKEN }}
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -0,0 +1,49 @@
+name: Docs Push
+
+on:
+  push:
+    branches: [ '**' ]
+    paths:
+      - 'docs/**'
+      - '.github/workflows/docs.yml'
+
+concurrency:
+    group: pages-${{ github.ref }}
+    cancel-in-progress: true
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      deployments: write
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v4
+        with:
+          python-version: 3.x
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
+      - uses: actions/cache@v3
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+      - run: pip install -r requirements.txt
+        working-directory: docs
+#      - run: mkdocs build --verbose --strict
+      - run: mkdocs build --verbose
+        working-directory: docs
+      - uses: actions/upload-pages-artifact@v1
+        with:
+          path: 'site'
+      - uses: cloudflare/pages-action@v1
+        with:
+          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+          projectName: ${{ vars.CLOUDFLARE_PROJECT_NAME }}
+          directory: site
+          gitHubToken: ${{ secrets.GITHUB_TOKEN }}
+          wranglerVersion: '3'
diff --git a/.gitignore b/.gitignore
@@ -20,3 +20,5 @@ build/*
 gradle.properties
 application.yml
 LavalinkServer/plugins
+.cache/
+site/
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -39,6 +39,13 @@ The most noteworthy of these, as well as any features and breaking changes, are
 Contributors:
 [@topi314](https://github.com/topi314), [@freyacodes](https://github.com/freyacodes), [@DRSchlaubi](https://github.com/DRSchlaubi) and [@melike2d](https://github.com/melike2d)
 
+## 3.7.8
+* Fix YouTube 403 errors
+* Fix YouTube access token errors
+
+## 3.7.7
+* Add JDA-NAS support for musl (`x86-64`, `aarch64`) based systems (most notably `alpine`)
+
 ## 3.7.6
 * Update Lavaplayer to [`1.4.1`](https://github.com/Walkyst/lavaplayer-fork/releases/tag/1.4.1) & [`1.4.2`](https://github.com/Walkyst/lavaplayer-fork/releases/tag/1.4.2)
 * New support for `MUSL` based systems (most notably `alpine`)

diff --git a/README.md b/README.md
@@ -14,6 +14,12 @@ A [basic example bot](Testbot) is available.
 > [!Warning]
 > Lavalink v4 is now in beta! See [the changelog](CHANGELOG.md) for more information.
 
+## Getting started
+* Pick one of the [up-to-date clients](https://lavalink.dev/clients). Advanced users can create their own using the [API documentation
+](https://lavalink.dev/api/)
+* See the [server configuration documentation](https://lavalink.dev/configuration/) for configuring your Lavalink server
+* Explore [available plugins](https://lavalink.dev/plugins) for extra features
+* See also our [FAQ](https://lavalink.dev/getting-started/faq)
 <details>
 <summary>Table of Contents</summary>
 
@@ -22,12 +28,6 @@ A [basic example bot](Testbot) is available.
 - [Hardware Support](#hardware-support)
 - [Changelog](#changelog)
 - [Versioning policy](#versioning-policy)
-- [Client libraries](#client-libraries)
-- [Server configuration](#server-configuration)
-  - [Config](#config)
-  - [Binary](#binary)
-  - [Systemd Serivce](#systemd-service)
-  - [Docker](#docker)
 
 </details>
 
@@ -95,236 +95,5 @@ Version numbers can come in different combinations, depending on the release typ
     `MAJOR.MINOR.PATCH-PRERELEASE` - Pre-release
     `MAJOR.MINOR.PATCH-PRERELEASE+BUILD` - Pre-release additional build metadata
 
----
 
-## Client libraries:
-| Client                                                                    | Platform        | Compatible With                            | Additional Information          |
-|---------------------------------------------------------------------------|-----------------|--------------------------------------------|---------------------------------|
-| [Lavalink-Client](https://github.com/lavalink-devs/Lavalink-Client)       | Java/Kotlin/JVM | JDA/Discord4J/**Any**                      | Uses reactor                    |
-| [Lavalink.kt](https://github.com/DRSchlaubi/Lavalink.kt)                  | Kotlin          | Kord/JDA/**Any**                           | Kotlin Coroutines               |
-| [DisGoLink](https://github.com/disgoorg/disgolink)                        | Go              | **Any**                                    |                                 |
-| [Mafic](https://github.com/ooliver1/mafic)                                | Python          | discord.py **V2**/nextcord/disnake/py-cord |                                 |
-| [Wavelink](https://github.com/PythonistaGuild/Wavelink/tree/feature/v3) | Python          | discord.py **V2**                          | Pre-Release (Version 3+)        |
-| [Moonlink.js](https://github.com/1Lucas1apk/moonlink.js)                  | Node.js         | **Any**                                    |                                 |
-| [Magmastream](https://github.com/Blackfort-Hosting/magmastream)           | Node.js         | **Any**                                    |                                 |
-| [Lavacord](https://github.com/lavacord/Lavacord)                          | Node.js         | **Any**                                    |                                 |
-| [Shoukaku](https://github.com/Deivu/Shoukaku)                             | Node.js         | **Any**                                    |                                 |
-| [Lavalink-Client](https://github.com/tomato6966/Lavalink-Client)          | Node.js         | **Any**                                    |                                 |
-| [FastLink](https://github.com/PerformanC/FastLink)                        | Node.js         | **Any**                                    |                                 |
-| [Riffy](https://github.com/riffy-team/riffy)                              | Node.js         | **Any**                                    |                                 |
-| [DisCatSharp](https://github.com/Aiko-IT-Systems/DisCatSharp)             | .NET            | DisCatSharp                                | v10.4.2+                        |
-| [Lavalink4NET](https://github.com/angelobreuer/Lavalink4NET)              | .NET            | Discord.Net/DSharpPlus/Remora              | v4+                             |
-| [Coglink](https://github.com/PerformanC/Coglink)                          | C               | Concord                                    |                                 |
-| [lavalink-rs](https://gitlab.com/vicky5124/lavalink-rs)                   | Rust, Python    | **Any**                                    | `tokio`-based, `asyncio`-based  |
 
-<details>
-<summary>v3.7 supporting Client Libraries</summary>
-
-| Client                                                        | Platform | Compatible With                            | Additional Information          |
-|---------------------------------------------------------------|----------|--------------------------------------------|---------------------------------|
-| [Lavalink.kt](https://github.com/DRSchlaubi/lavalink.kt)      | Kotlin   | JDA/Kord/**Any**                           | Kotlin Coroutines               |
-| [lavaplay.py](https://github.com/HazemMeqdad/lavaplay.py)     | Python   | **Any\***                                  | *`asyncio`-based libraries only |
-| [Mafic](https://github.com/ooliver1/mafic)                    | Python   | discord.py **V2**/nextcord/disnake/py-cord |                                 |
-| [Wavelink](https://github.com/PythonistaGuild/Wavelink)       | Python   | discord.py **V2**                          | Version >=2, <3                 |
-| [Pomice](https://github.com/cloudwithax/pomice)               | Python   | discord.py **V2**                          |                                 |
-| [Lavacord](https://github.com/lavacord/lavacord)              | Node.js  | **Any**                                    |                                 |
-| [Poru](https://github.com/parasop/poru)                       | Node.js  | **Any**                                    |                                 |
-| [Shoukaku](https://github.com/Deivu/Shoukaku)                 | Node.js  | **Any**                                    |                                 |
-| [Cosmicord.js](https://github.com/SudhanPlayz/Cosmicord.js)   | Node.js  | **Any**                                    |                                 |
-| [DisCatSharp](https://github.com/Aiko-IT-Systems/DisCatSharp) | .NET     | DisCatSharp                                | Only prior v10.4.1              |
-| [Nomia](https://github.com/DHCPCD9/Nomia)                     | .NET     | DSharpPlus                                 |                                 |
-| [Lavalink4NET](https://github.com/angelobreuer/Lavalink4NET)  | .NET     | Discord.Net/DSharpPlus                     | < v4                            |
-| [DisGoLink](https://github.com/disgoorg/disgolink)            | Go       | **Any**                                    |                                 |
-
-</details>
-
-Or alternatively, you can create your own client library, following the [implementation documentation](IMPLEMENTATION.md).
-Any client libraries marked with `Unmaintained` have been marked as such as their repositories have not received any commits for at least 1 year since time of checking,
-however they are listed as they may still support Lavalink, and/or have not needed maintenance, however keep in mind that compatibility and full feature support is not guaranteed.
-
-## Server configuration
-
-### Config
-
-The server configuration is done in `application.yml`. You can find an example configuration [here](LavalinkServer/application.yml.example).
-
-Alternatively, you can also use environment variables to configure the server. The environment variables are named the same as the keys in the `application.yml` file, but in uppercase and with `.` replaced with `_`. For example, `server.port` becomes `SERVER_PORT`.
-For arrays, the index is appended to the key, starting at 0. For example, `LAVALINK_PLUGINS_0_DEPENDENCY` refers to the `dependency` key of the first plugin.
-
-<details>
-<summary>List of all env keys</summary>
-
-```env
-SERVER_PORT
-SERVER_ADDRESS
-
-LAVALINK_PLUGINS_0_DEPENDENCY
-LAVALINK_PLUGINS_0_REPOSITORY
-
-LAVALINK_PLUGINS_1_DEPENDENCY
-LAVALINK_PLUGINS_1_REPOSITORY
-
-LAVALINK_PLUGINS_DIR
-
-LAVALINK_SERVER_PASSWORD
-LAVALINK_SERVER_SOURCES_YOUTUBE
-LAVALINK_SERVER_SOURCES_BANDCAMP
-LAVALINK_SERVER_SOURCES_SOUNDCLOUD
-LAVALINK_SERVER_SOURCES_TWITCH
-LAVALINK_SERVER_SOURCES_VIMEO
-LAVALINK_SERVER_SOURCES_HTTP
-LAVALINK_SERVER_SOURCES_LOCAL
-
-LAVALINK_SERVER_FILTERS_VOLUME
-LAVALINK_SERVER_FILTERS_EQUALIZER
-LAVALINK_SERVER_FILTERS_KARAOKE
-LAVALINK_SERVER_FILTERS_TIMESCALE
-LAVALINK_SERVER_FILTERS_TREMOLO
-LAVALINK_SERVER_FILTERS_VIBRATO
-LAVALINK_SERVER_FILTERS_DISTORTION
-LAVALINK_SERVER_FILTERS_ROTATION
-LAVALINK_SERVER_FILTERS_CHANNEL_MIX
-LAVALINK_SERVER_FILTERS_LOW_PASS
-
-LAVALINK_SERVER_BUFFER_DURATION_MS
-LAVALINK_SERVER_FRAME_BUFFER_DURATION_MS
-LAVALINK_SERVER_OPUS_ENCODING_QUALITY
-LAVALINK_SERVER_RESAMPLING_QUALITY
-LAVALINK_SERVER_TRACK_STUCK_THRESHOLD_MS
-LAVALINK_SERVER_USE_SEEK_GHOSTING
-
-LAVALINK_SERVER_PLAYER_UPDATE_INTERVAL
-LAVALINK_SERVER_YOUTUBE_SEARCH_ENABLED
-LAVALINK_SERVER_SOUNDCLOUD_SEARCH_ENABLED
-
-LAVALINK_SERVER_GC_WARNINGS
-
-LAVALINK_SERVER_RATELIMIT_IP_BLOCKS
-LAVALINK_SERVER_RATELIMIT_EXCLUDE_IPS
-LAVALINK_SERVER_RATELIMIT_STRATEGY
-LAVALINK_SERVER_RATELIMIT_SEARCH_TRIGGERS_FAIK
-LAVALINK_SERVER_RATELIMIT_RETRY_LIMIT
-
-LAVALINK_SERVER_YOUTUBE_CONFIG_EMAIL
-LAVALINK_SERVER_YOUTUBE_CONFIG_PASSWORD
-
-LAVALINK_SERVER_HTTP_CONFIG_PROXY_HOST
-LAVALINK_SERVER_HTTP_CONFIG_PROXY_PORT
-LAVALINK_SERVER_HTTP_CONFIG_PROXY_USER
-LAVALINK_SERVER_HTTP_CONFIG_PROXY_PASSWORD
-
-METRICS_PROMETHEUS_ENABLED
-METRICS_PROMETHEUS_ENDPOINT
-
-SENTRY_DSN
-SENTRY_ENVIRONMENT
-SENTRY_TAGS_SOME_KEY
-SENTRY_TAGS_ANOTHER_KEY
-
-LOGGING_FILE_PATH
-LOGGING_LEVEL_ROOT
-LOGGING_LEVEL_LAVALINK
-
-LOGGING_REQUEST_ENABLED
-LOGGING_REQUEST_INCLUDE_CLIENT_INFO
-LOGGING_REQUEST_INCLUDE_HEADERS
-LOGGING_REQUEST_INCLUDE_QUERY_STRING
-LOGGING_REQUEST_INCLUDE_PAYLOAD
-LOGGING_REQUEST_MAX_PAYLOAD_LENGTH
-
-LOGGING_LOGBACK_ROLLINGPOLICY_MAX_FILE_SIZE
-LOGGING_LOGBACK_ROLLINGPOLICY_MAX_HISTORY
-```
-</details>
-
-
-### Binary
-Download binaries from the [Download Server](https://repo.arbjerg.dev/artifacts/lavalink/), [GitHub releases](https://github.com/lavalink-devs/Lavalink/releases) (specific versions prior to `v3.5` can be found in the [CI Server](https://ci.fredboat.com/viewLog.html?buildId=lastSuccessful&buildTypeId=Lavalink_Build&tab=artifacts&guest=1)) or [GitHub actions](https://github.com/lavalink-devs/Lavalink/actions).
-
-Put an `application.yml` file in your working directory. ([Example here](LavalinkServer/application.yml.example))
-
-Run with `java -jar Lavalink.jar` from the same directory
-
-### Systemd Service
-
-If you're using a Systemd-based Linux distribution you may want to install Lavalink as a background service. You will need to create a `lavalink.service` file inside `/usr/lib/systemd/system`. Create the file with the following template (replacing the values inside the `<>` brackets):
- ```ini
-[Unit]
-# Describe the service
-Description=Lavalink Service
-
-# Configure service order
-After=syslog.target network.target
-
-[Service]
-# The user which will run Lavalink
-User=<usr>
-
-# The group which will run Lavalink
-Group=<usr>
-
-# Where the program should start
-WorkingDirectory=</home/usr/lavalink>
-
-# The command to start Lavalink
-ExecStart=java -Xmx4G -jar </home/usr/lavalink>/Lavalink.jar
-
-# Restart the service if it crashes
-Restart=on-failure
-
-# Delay each restart by 5s
-RestartSec=5s
-
-[Install]
-# Start this service as part of normal system start-up
-WantedBy=multi-user.target
-```
-
-To initiate the service, run 
-
-```shell
-sudo systemctl daemon-reload
-sudo systemctl enable lavalink
-sudo systemctl start lavalink
-```
-
-In addition to the usual log files, you can also view the log with `sudo journalctl -u lavalink`.
-
-### Docker
-
-Docker images can be found under [packages](https://github.com/lavalink-devs/Lavalink/pkgs/container/lavalink) with old builds prior to `v3.7.4` being available on [Docker Hub](https://hub.docker.com/r/fredboat/lavalink/).
-There are 2 image variants `Ubuntu` and `Alpine`, the `Alpine` variant is smaller and can be used with the `-alpine` suffix, for example `ghcr.io/lavalink-devs/lavalink:3-alpine`.
-
-Install [Docker](https://docs.docker.com/engine/install/) & [Docker Compose](https://docs.docker.com/compose/install/)
-
-Create a `docker-compose.yml` with the following content:
-```yaml
-version: "3.8"
-
-services:
-    lavalink:
-        image: ghcr.io/lavalink-devs/lavalink:4 # pin the image version to Lavalink v4
-        container_name: lavalink
-        restart: unless-stopped
-        environment:
-            - _JAVA_OPTIONS=-Xmx6G # set Java options here
-            - SERVER_PORT=2333 # set lavalink server port
-            - LAVALINK_SERVER_PASSWORD=youshallnotpass # set password for lavalink
-        volumes:
-            - ./application.yml:/opt/Lavalink/application.yml # mount application.yml from the same directory or use environment variables
-            - ./plugins/:/opt/Lavalink/plugins/ # persist plugins between restarts, make sure to set the correct permissions (user: 322, group: 322)
-        networks:
-            - lavalink
-        expose:
-            - 2333 # lavalink exposes port 2333 to connect to for other containers (this is for documentation purposes only)
-        ports:
-            - 2333:2333 # you only need this if you want to make your lavalink accessible from outside of containers
-networks:
-    lavalink: # create a lavalink network you can add other containers to, to give them access to Lavalink
-        name: lavalink
-```
-
-Run `docker compose up -d`. See [Docker Compose Up](https://docs.docker.com/engine/reference/commandline/compose_up/)
-
-If your bot also runs in a docker container you can make that container join the lavalink network and use `lavalink` (service name) as the hostname to connect.
-See [Docker Networking](https://docs.docker.com/network/) & [Docker Compose Networking](https://docs.docker.com/compose/networking/)
diff --git a/branding/lavalink-400.png b/branding/lavalink-400.png