Skip to content

Latest commit

 

History

History
198 lines (191 loc) · 17.3 KB

SETUP.md

File metadata and controls

198 lines (191 loc) · 17.3 KB

Setup

Note

  • PyLav assumes you are using PostgresSQL server running version 14, and it also requires Python3.11 any other version for these will not work/be supported.
  • If you have docker; Setting up a postgres container for it would likely be the simplest option to set up the necessary server.
  • If you have docker you can use the Lavalink v4 image instead of installing Java for more info see discord

Warning You should be using docker and using the provided docker-compose file for the easiest setup.

With Docker

  • A custom docker-compose file can be found here
    • This uses a custom fork of Phasecore's redbot image to add support for python3.11 with PyLav bundled in i.e. docker-red-discordbot
  • If using this setup make sure to use this pylav.yaml file for the PyLav config.

Without Docker

  • Download the latest Lavalink v4 from the Lavalink Release
  • Place these a directory of your choice.
  • Edit the custom application.yml (Deezer is disabled by default) to your liking changing the CHANGE_ME values, if you need help with this please join the Discord support server
  • Start an unmanaged Lavalink node using the application.yml you just edited and the Lavalink.jar you just downloaded.
  • Make the following changes to your pylav.yaml config file
    • Set PYLAV__EXTERNAL_UNMANAGED_HOST to localhost
    • Set PYLAV__EXTERNAL_UNMANAGED_PASSWORD to the password in the lavalink.server section of the application.yml file
    • Set PYLAV__EXTERNAL_UNMANAGED_PORT to the port in the server section of thee application.yml file (Default is 2154)
    • Set PYLAV__EXTERNAL_UNMANAGED_SSL to false
    • Set PYLAV__MANAGED_NODE_SPOTIFY_CLIENT_ID to the clientId in the plugins.lavasrc.spotify section of the application.yml file
    • Set PYLAV__MANAGED_NODE_SPOTIFY_CLIENT_SECRET to the clientSecret in the plugins.lavasrc.spotify section of the application.yml file
    • Set PYLAV__MANAGED_NODE_SPOTIFY_COUNTRY_CODE to the countryCode in the plugins.lavasrc.spotify section of the application.yml file
    • Set PYLAV__MANAGED_NODE_APPLE_MUSIC_API_KEY to the mediaAPIToken in the plugins.lavasrc.applemusic section of the application.yml file or if none leave it empty
    • Set PYLAV__MANAGED_NODE_APPLE_MUSIC_COUNTRY_CODE to the countryCode in the plugins.lavasrc.applemusic section of the application.yml file
    • Set PYLAV__MANAGED_NODE_YANDEX_MUSIC_ACCESS_TOKEN to the accessToken in the plugins.lavasrc.yandexmusic section of the application.yml file or if none leave it empty

Linux (Ubuntu 22.04)

If you are not on Ubuntu 20.04 you just have to follow the instructions below to install the dependencies and set them up for your Linux distro (Google is your friend).

  • libaio

    • sudo apt install libaio1 libaio-dev

  • Postgres14

    • Follow the installation instruction here
      • Note: When prompted to run sudo apt-get -y install postgresql make sure to run sudo apt-get -y install postgresql-14 instead.
      • Create a new Postgres user
        • sudo -u postgres createuser -s -i -d -r -l -w <username>
          • -s User will be a superuser
          • -i User will inherit permissions from roles granted to it
          • -d User can create databases
          • -r User can create roles
          • -l User can log in
          • -w User will never be prompted for a password. If the server requires password authentication and a password is not available by other means, the connection attempt will fail.
        • sudo -u postgres psql -c "ALTER ROLE <username> WITH PASSWORD '<password>';"
          • Make sure to replace <username> and <password> with the new values
      • Create a new Database for the new user
        • Run sudo -u postgres psql -c "CREATE DATABASE pylav_db;"
          • This will crete a new database called pylav_db.
        • Run sudo -u postgres psql -c "ALTER DATABASE pylav_db OWNER TO <username>;"
          • This will set the owner of the database to the newly created user.
      • Enable PostgresSQL extensions (NOTICE - PyLav will do this for you if they are not enabled, however depending on your setup you may need to enable them manually)
        • Run sudo -u postgres psql -c "CREATE EXTENSION IF NOT EXISTS citext;"
        • Run sudo -u postgres psql -c "CREATE EXTENSION IF NOT EXISTS pg_trgm;"
        • Run sudo -u postgres psql -c 'CREATE EXTENSION IF NOT EXISTS "uuid-ossp";'

  • Install Java Azul Zulu 19

    • Follow the instructions here
      • When prompted to run sudo apt-get install zulu11-jdk make sure to run sudo apt-get install zulu19-ca-jdk-headless instead.

Mac

  • Postgres14

    • Follow the installation instruction here
    • Create a new Postgres user
      • Open the psql command-line tool and login when prompted
      • Run psql -u postgres to login as the user postgres
      • When logged in run CREATE ROLE <username> LOGIN PASSWORD '<password>';
        • Make sure to replace <username> and <password> with the new values
    • Create a new Database for the new user
      • Run CREATE DATABASE pylav_db;
        • This will crete a new database called pylav_db.
      • Run ALTER DATABASE pylav_db OWNER TO <username>;
        • This will set the owner of the database to the newly created user.
    • Enable PostgresSQL extensions (NOTICE - PyLav will do this for you if they are not enabled, however depending on your setup you may need to enable them manually)
      • Run CREATE EXTENSION IF NOT EXISTS citext;
      • Run CREATE EXTENSION IF NOT EXISTS pg_trgm;
      • Run CREATE EXTENSION IF NOT EXISTS "uuid-ossp";

  • Install Java Azul Zulu 19

    • Download and run the dmg executable here

Windows

  • Postgres14

    • Follow the installation instruction here
    • Create a new Postgres user
      • Open the psql command-line tool and login when prompted
      • Run psql -u postgres to login as the user postgres
      • When logged in run CREATE ROLE <username> LOGIN PASSWORD '<password>';
        • Make sure to replace <username> and <password> with the new values
    • Create a new Database for the new user
      • Run CREATE DATABASE pylav_db;
        • This will crete a new database called pylav_db.
      • Run ALTER DATABASE pylav_db OWNER TO <username>;
        • This will set the owner of the database to the newly created user.
    • Enable PostgresSQL extensions (NOTICE - PyLav will do this for you if they are not enabled, however depending on your setup you may need to enable them manually)
      • Run CREATE EXTENSION IF NOT EXISTS citext;
      • Run CREATE EXTENSION IF NOT EXISTS pg_trgm;
      • Run CREATE EXTENSION IF NOT EXISTS "uuid-ossp";

  • Install Java Azul Zulu 19

    • Download and run the msi executable here
      • Make sure to select the following when prompted Add to PATH, set JAVA_HOME variable and JavaSoft (Oracle) registry keys

Environment Variables

Note - All environment variables except PYLAV__LOGGER_PREFIX and PYLAV__YAML_CONFIG can be configured from the pylav.yaml file which should reside in the home directory of the user running the bot. An example of the file can be found at pylav.example.yaml, if you don't create the file yourself pylav will do so on the first run.

  • PYLAV__YAML_CONFIG:
    • If you are in an environment where the home directory is not available you can specify a path to the config file using the PYLAV__YAML_CONFIG environment variable.
    • This should be the absolute path to the pylav.yaml file i.e /config/pylav.yaml.
  • PYLAV__LOGGER_PREFIX:
    • The prefix to use for the logger, defaults nothing, if provided all loggers used by PyLav will be prefixed with this value.

pylav.yaml Setup (Non-Docker)

  • Go to your home directory for the user which will run the bot.

    • Windows
      • Run cd %userprofile%
    • Mac/Linux
      • Run cd ~

  • Make a copy of pylav.example.yaml to your home directory and name it pylav.yaml

  • Change the values inside the pylav.yaml to the desired values

    • Change PYLAV__POSTGRES_PASSWORD from changeme to the password of the Postgres user you created above.
    • Change PYLAV__POSTGRES_USER from changeme to the user you created above.
    • Change PYLAV__POSTGRES_DB from pylav_db to the name of the database you created above (if you followed the commands above it should be pylav_db).
    • Change PYLAV__POSTGRES_PORT and PYLAV__POSTGRES_HOST to the connection host and port for the Postgres server.
    • To use a Unix socket instead of TCP
    • Provide the PYLAV__POSTGRES_SOCKET variable. If this is provided PYLAV__POSTGRES_HOST and PYLAV__POSTGRES_PORT will be ignored.
    • PYLAV__JAVA_EXECUTABLE can be changed from java to the full path of the Azul Zulu 19 Java executable installed above.
      • By default, it will use java to ensure you have the correct version under java run java --version if it says "OpenJDK Runtime Environment Zulu19..." then this is not needed to be changed.
    • If you don't want PyLav to manage a node (not recommended) you can specify the connection args from an external node instead.
      • Note: PyLav supports multiple bots running on the sam
      • e machine, this should not be the reason why you set these.
        • Set PYLAV__EXTERNAL_UNMANAGED_HOST to the Lavalink node connection host
        • Set PYLAV__EXTERNAL_UNMANAGED_PASSWORD to the Lavalink node connection auth password.
        • Set PYLAV__EXTERNAL_UNMANAGED_PORT to the Lavalink node connection port - If this is not specified the node will use port 80 if PYLAV__EXTERNAL_UNMANAGED_SSL is set to false or 443 if PYLAV__EXTERNAL_UNMANAGED_SSL is set to true.
        • Set PYLAV__EXTERNAL_UNMANAGED_SSL to true or false depending on weather or not the external node is using SSL
        • Set PYLAV__EXTERNAL_UNMANAGED_NAME to the name of the external node (this is used for logging and event references)

  • If you already have a Redis server and want to make use of it for the request cache you can set PYLAV__REDIS_FULL_ADDRESS_RESPONSE_CACHE to the full connection url of your existing server.

    • e.g. redis://[[username]:[password]]@localhost:6379/0
    • e.g. unix://[[username]:[password]]@/path/to/socket.sock?db=0

  • If you want to change the frequency of Playlist update tasks you can change the values of the following, note it will only get applied for the next cycle.

    • PYLAV__TASK_TIMER_UPDATE_BUNDLED_PLAYLISTS_DAYS: Defaults to 1 # How many days to wait between updates - Minimum 1 Day.
    • PYLAV__TASK_TIMER_UPDATE_BUNDLED_EXTERNAL_PLAYLISTS_DAYS: Defaults to 7 # How many days to wait between updates - Minimum 7 Days.
    • PYLAV__TASK_TIMER_UPDATE_EXTERNAL_PLAYLISTS_DAYS: Defaults to 7 # How many days to wait between updates - Minimum 7 Days.

  • If you want PyLav to cache most of the queries from the Postgres server you can use PYLAV__READ_CACHING_ENABLED

    DO NOTE: If this is set to true multiple bots should not share the same database (The can still share the same Postgres server, just not the same database), as reads and writes will be out of sync.

    • If this is turned off every read from the database will be a direct query to the database, if this is turned on PyLav will cache the results in memory after the first query.
      • If you have a remote server, this will likely be a good idea to turn on, however you loose the ability to manually or otherwise edit the db and changes to be reflected in PyLav. - I would recommend enabling this ONLY if you notice slow operation with a remove Postgres server.

  • Optional configuration values

    • PYLAV__DEFAULT_SEARCH_SOURCE: Defaults to dzsearch - Possible values are dzsearch (Deezer), spsearch (Spotify), amsearch (Apple Music), ytmsearch (YouTube Music), ytsearch (YouTube)
    • PYLAV__MANAGED_NODE_SPOTIFY_CLIENT_ID: Defaults to None - Required if you want to use Spotify with the managed node
    • PYLAV__MANAGED_NODE_SPOTIFY_CLIENT_SECRET: Defaults to None - Required if you want to use Spotify with the managed node
    • PYLAV__MANAGED_NODE_SPOTIFY_COUNTRY_CODE: Defaults to US
    • PYLAV__MANAGED_NODE_APPLE_MUSIC_API_KEY - Defaults to None
    • PYLAV__MANAGED_NODE_APPLE_MUSIC_COUNTRY_CODE : Defaults to US
    • PYLAV__MANAGED_NODE_YANDEX_MUSIC_ACCESS_TOKEN - Defaults to None - Required if you want to use Yandex with the managed node
    • PYLAV__MANAGED_NODE_DEEZER_KEY - Required if you want to use Deezer, leave empty unless you know what you are doing

pylav.yaml Setup (Docker)

  • Make a copy of pylav.docker.yaml and mount it to any chosen path i.e ./pylav.docker.yaml:/pylav/pylav.yaml
  • On your container set the following environment variables:
    • PYLAV__YAML_CONFIG=/pylav/pylav.yaml
  • Change the values inside the pylav.yaml to the desired values
    • PYLAV__JAVA_EXECUTABLE Not applicable leave it as java, in a docket setup set the following environment variable instead:
    • Set PYLAV__EXTERNAL_UNMANAGED_HOST to the Lavalink node connection host
    • Set PYLAV__EXTERNAL_UNMANAGED_PASSWORD to the Lavalink node connection auth password.
    • Set PYLAV__EXTERNAL_UNMANAGED_PORT to the Lavalink node connection port - If this is not specified the node will use port 80 if PYLAV__EXTERNAL_UNMANAGED_SSL is set to false or 443 if PYLAV__EXTERNAL_UNMANAGED_SSL is set to true.
    • Set PYLAV__EXTERNAL_UNMANAGED_SSL to false depending on weather or not the external node is using SSL
  • If you already have a Redis server and want to make use of it for the request cache you can set PYLAV__REDIS_FULL_ADDRESS_RESPONSE_CACHE to the full connection url of your existing server.
    • e.g. redis://[[username]:[password]]@localhost:6379/0
    • e.g. unix://[[username]:[password]]@/path/to/socket.sock?db=0
  • If you want to change the frequency of Playlist update tasks you can change the values of the following, note it will only get applied for the next cycle.
    • PYLAV__TASK_TIMER_UPDATE_BUNDLED_PLAYLISTS_DAYS: Defaults to 1 # How many days to wait between updates - Minimum 1 Day.
    • PYLAV__TASK_TIMER_UPDATE_BUNDLED_EXTERNAL_PLAYLISTS_DAYS: Defaults to 7 # How many days to wait between updates - Minimum 7 Days.
    • PYLAV__TASK_TIMER_UPDATE_EXTERNAL_PLAYLISTS_DAYS: Defaults to 7 # How many days to wait between updates - Minimum 7 Days.
  • If you want PyLav to cache most of the queries from the Postgres server you can use PYLAV__READ_CACHING_ENABLED

    DO NOTE: If this is set to true multiple bots should not share the same database (The can still share the same Postgres server, just not the same database), as reads and writes will be out of sync.

    • If this is turned off every read from the database will be a direct query to the database, if this is turned on PyLav will cache the results in memory after the first query.
      • If you have a remote server, this will likely be a good idea to turn on, however you loose the ability to manually or otherwise edit the db and changes to be reflected in PyLav. - I would recommend enabling this ONLY if you notice slow operation with a remove Postgres server.
  • Optional configuration values
    • PYLAV__DEFAULT_SEARCH_SOURCE: Defaults to dzsearch - Possible values are dzsearch (Deezer), spsearch (Spotify), amsearch (Apple Music), ytmsearch (YouTube Music), ytsearch (YouTube)
    • PYLAV__MANAGED_NODE_SPOTIFY_CLIENT_ID: Defaults to None - Required if you want to use Spotify
    • PYLAV__MANAGED_NODE_SPOTIFY_CLIENT_SECRET: Defaults to None - Required if you want to use Spotify
    • PYLAV__MANAGED_NODE_SPOTIFY_COUNTRY_CODE: Defaults to US
    • PYLAV__MANAGED_NODE_APPLE_MUSIC_API_KEY - Defaults to None
    • PYLAV__MANAGED_NODE_APPLE_MUSIC_COUNTRY_CODE : Defaults to US
    • PYLAV__MANAGED_NODE_YANDEX_MUSIC_ACCESS_TOKEN - Defaults to None - Required if you want to use Yandex
    • PYLAV__MANAGED_NODE_DEEZER_KEY - Required if you want to use Deezer, leave empty unless you know what you are doing
    • PYLAV__LOCAL_TRACKS_FOLDER - Defaults to a "music" folder created inside PyLav's data folder
    • PYLAV__DATA_FOLDER - Default of an OS appropriate config folder

Red Users (PyLav Cogs) Setup

Install PyLav Cogs

  • Now that you have your env fully setup you can process to installing the desired cogs.
    • [p]load downloader
    • [p]repo add PyLav https://github.com/PyLav/Red-Cogs
  • For a list of all available cogs visit the PyLav Cogs repo