From ce031cf7bd6ee50af6888e6877558ff27990d800 Mon Sep 17 00:00:00 2001 From: Toby Harradine Date: Sun, 26 Aug 2018 23:44:56 +1000 Subject: [PATCH] [Docs] Add virtualenv guide and compress install guides (#2029) * [Docs] Add virtualenv guide and compress install guides Signed-off-by: Toby Harradine * [Docs] Better cross-referencing Signed-off-by: Toby Harradine * Fix pyenv-installer link Signed-off-by: Toby Harradine * Use sudo -e instead of sudo nano * Add note about launcher for linux/mac * Include launcher notes in Windows guide * Add missing colon --- docs/autostart_systemd.rst | 2 +- docs/index.rst | 9 +- docs/install_arch.rst | 55 --------- docs/install_centos.rst | 55 --------- docs/install_debian.rst | 70 ------------ docs/install_linux_mac.rst | 203 +++++++++++++++++++++++++++++++++ docs/install_mac.rst | 53 --------- docs/install_raspbian.rst | 72 ------------ docs/install_ubuntu_bionic.rst | 54 --------- docs/install_ubuntu_xenial.rst | 59 ---------- docs/install_windows.rst | 75 ++++++++++-- docs/venv_guide.rst | 132 +++++++++++++++++++++ 12 files changed, 401 insertions(+), 438 deletions(-) delete mode 100644 docs/install_arch.rst delete mode 100644 docs/install_centos.rst delete mode 100644 docs/install_debian.rst create mode 100644 docs/install_linux_mac.rst delete mode 100644 docs/install_mac.rst delete mode 100644 docs/install_raspbian.rst delete mode 100644 docs/install_ubuntu_bionic.rst delete mode 100644 docs/install_ubuntu_xenial.rst create mode 100644 docs/venv_guide.rst diff --git a/docs/autostart_systemd.rst b/docs/autostart_systemd.rst index abad039e7..90351bbd5 100644 --- a/docs/autostart_systemd.rst +++ b/docs/autostart_systemd.rst @@ -10,7 +10,7 @@ Creating the service file Create the new service file: -:code:`sudo nano /etc/systemd/system/red@.service` +:code:`sudo -e /etc/systemd/system/red@.service` Paste the following and replace all instances of :code:`username` with the username your bot is running under (hopefully not root): diff --git a/docs/index.rst b/docs/index.rst index 680cca4f4..8a3d2e60a 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -11,13 +11,8 @@ Welcome to Red - Discord Bot's documentation! :caption: Installation Guides: install_windows - install_mac - install_ubuntu_xenial - install_ubuntu_bionic - install_debian - install_centos - install_arch - install_raspbian + install_linux_mac + venv_guide cog_dataconverter autostart_systemd diff --git a/docs/install_arch.rst b/docs/install_arch.rst deleted file mode 100644 index 4b07ac4c3..000000000 --- a/docs/install_arch.rst +++ /dev/null @@ -1,55 +0,0 @@ -.. arch install guide - -============================== -Installing Red on Arch Linux -============================== - -.. warning:: For safety reasons, DO NOT install Red with a root user. Instead, make a new one. - -:code:`https://wiki.archlinux.org/index.php/Users_and_groups` - -------------------------------- -Installing the pre-requirements -------------------------------- - -.. code-block:: none - - sudo pacman -Syu python-pip git base-devel jre8-openjdk - ------------------- -Installing the bot ------------------- - -To install without audio: - -:code:`pip3 install -U --process-dependency-links red-discordbot --user` - -To install with audio: - -:code:`pip3 install -U --process-dependency-links red-discordbot[voice] --user` - -To install the development version (without audio): - -:code:`pip3 install -U --process-dependency-links git+https://github.com/Cog-Creators/Red-DiscordBot@V3/develop#egg=red-discordbot --user` - -To install the development version (with audio): - -:code:`pip3 install -U --process-dependency-links git+https://github.com/Cog-Creators/Red-DiscordBot@V3/develop#egg=red-discordbot[voice] --user` - ------------------------- -Setting up your instance ------------------------- - -Run :code:`redbot-setup` and follow the prompts. It will ask first for where you want to -store the data (the default is :code:`~/.local/share/Red-DiscordBot`) and will then ask -for confirmation of that selection. Next, it will ask you to choose your storage backend -(the default here is JSON). It will then ask for a name for your instance. This can be -anything as long as it does not contain spaces; however, keep in mind that this is the -name you will use to run your bot, and so it should be something you can remember. - ------------ -Running Red ------------ - -Run :code:`redbot ` and run through the initial setup. This will ask for -your token and a prefix. diff --git a/docs/install_centos.rst b/docs/install_centos.rst deleted file mode 100644 index 054f21c2e..000000000 --- a/docs/install_centos.rst +++ /dev/null @@ -1,55 +0,0 @@ -.. centos install guide - -========================== -Installing Red on CentOS 7 -========================== - -.. warning:: For safety reasons, DO NOT install Red with a root user. Instead, `make a new one `_. - ---------------------------- -Installing pre-requirements ---------------------------- - -.. code-block:: none - - yum -y groupinstall development - yum -y install https://centos7.iuscommunity.org/ius-release.rpm - yum -y install yum-utils wget which python36u python36u-pip python36u-devel openssl-devel libffi-devel git java-1.8.0-openjdk - --------------- -Installing Red --------------- - -Without audio: - -:code:`pip3 install -U --process-dependency-links red-discordbot --user` - -With audio: - -:code:`pip3 install -U --process-dependency-links red-discordbot[voice] --user` - -To install the development version (without audio): - -:code:`pip3 install -U --process-dependency-links git+https://github.com/Cog-Creators/Red-DiscordBot@V3/develop#egg=red-discordbot --user` - -To install the development version (with audio): - -:code:`pip3 install -U --process-dependency-links git+https://github.com/Cog-Creators/Red-DiscordBot@V3/develop#egg=red-discordbot[voice] --user` - ----------------------- -Setting up an instance ----------------------- - -Run :code:`redbot-setup` and follow the prompts. It will ask first for where you want to -store the data (the default is :code:`~/.local/share/Red-DiscordBot`) and will then ask -for confirmation of that selection. Next, it will ask you to choose your storage backend -(the default here is JSON). It will then ask for a name for your instance. This can be -anything as long as it does not contain spaces; however, keep in mind that this is the -name you will use to run your bot, and so it should be something you can remember. - ------------ -Running Red ------------ - -Run :code:`redbot ` and run through the initial setup. This will ask for -your token and a prefix. diff --git a/docs/install_debian.rst b/docs/install_debian.rst deleted file mode 100644 index 4bd58f610..000000000 --- a/docs/install_debian.rst +++ /dev/null @@ -1,70 +0,0 @@ -.. debian install guide - -================================ -Installing Red on Debian Stretch -================================ - -.. warning:: For safety reasons, DO NOT install Red with a root user. Instead, `make a new one `_. - ---------------------------- -Installing pre-requirements ---------------------------- - -.. code-block:: none - - sudo apt install -y make build-essential libssl-dev zlib1g-dev libbz2-dev libreadline-dev libsqlite3-dev wget curl llvm libncurses5-dev libncursesw5-dev xz-utils tk-dev libffi-dev git unzip default-jre - curl -L https://github.com/pyenv/pyenv-installer/raw/master/bin/pyenv-installer | bash - -After that last command, you may see a warning about 'pyenv' not being in the load path. Follow the instructions given to fix that, then close and reopen your shell - -Then run the following command: - -.. code-block:: none - - CONFIGURE_OPTS=--enable-optimizations pyenv install 3.6.5 -v - -This may take a long time to complete. - -After that is finished, run: - -.. code-block:: none - - pyenv global 3.6.5 - ------------------- -Installing the bot ------------------- - -To install without audio: - -:code:`pip3 install -U --process-dependency-links red-discordbot` - -To install with audio: - -:code:`pip3 install -U --process-dependency-links red-discordbot[voice]` - -To install the development version (without audio): - -:code:`pip3 install -U --process-dependency-links git+https://github.com/Cog-Creators/Red-DiscordBot@V3/develop#egg=red-discordbot` - -To install the development version (with audio): - -:code:`pip3 install -U --process-dependency-links git+https://github.com/Cog-Creators/Red-DiscordBot@V3/develop#egg=red-discordbot[voice]` - ------------------------- -Setting up your instance ------------------------- - -Run :code:`redbot-setup` and follow the prompts. It will ask first for where you want to -store the data (the default is :code:`~/.local/share/Red-DiscordBot`) and will then ask -for confirmation of that selection. Next, it will ask you to choose your storage backend -(the default here is JSON). It will then ask for a name for your instance. This can be -anything as long as it does not contain spaces; however, keep in mind that this is the -name you will use to run your bot, and so it should be something you can remember. - ------------ -Running Red ------------ - -Run :code:`redbot ` and run through the initial setup. This will ask for -your token and a prefix. diff --git a/docs/install_linux_mac.rst b/docs/install_linux_mac.rst new file mode 100644 index 000000000..117df334c --- /dev/null +++ b/docs/install_linux_mac.rst @@ -0,0 +1,203 @@ +.. _linux-mac-install-guide: + +============================== +Installing Red on Linux or Mac +============================== + +.. warning:: + + For safety reasons, DO NOT install Red with a root user. If you are unsure how to create + a new user, see the man page for the ``useradd`` command. + +------------------------------- +Installing the pre-requirements +------------------------------- + +Please install the pre-requirements using the commands listed for your operating system. + +The pre-requirements are: + - Python 3.6 or greater + - pip 9.0 or greater + - git + - Java Runtime Environment 8 or later (for audio support) + +~~~~~~~~~~ +Arch Linux +~~~~~~~~~~ + +.. code-block:: none + + sudo pacman -Syu python-pip git base-devel jre8-openjdk + +~~~~~~~~ +CentOS 7 +~~~~~~~~ + +.. code-block:: none + + yum -y groupinstall development + yum -y install https://centos7.iuscommunity.org/ius-release.rpm + yum -y install yum-utils wget which python36u python36u-pip python36u-devel openssl-devel libffi-devel git java-1.8.0-openjdk + +~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Debian and Raspbian Stretch +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. warning:: + + Audio will not work on Raspberry Pi's **below** 2B. This is a CPU problem and + *cannot* be fixed. + +We recommend installing pyenv as a method of installing non-native versions of python on +Debian/Raspbian Stretch. This guide will tell you how. First, run the following commands: + +.. code-block:: none + + sudo apt install -y make build-essential libssl-dev zlib1g-dev libbz2-dev libreadline-dev libsqlite3-dev wget curl llvm libncurses5-dev libncursesw5-dev xz-utils tk-dev libffi-dev git unzip default-jre + curl -L https://github.com/pyenv/pyenv-installer/raw/master/bin/pyenv-installer | bash + +After that last command, you may see a warning about 'pyenv' not being in the load path. Follow the +instructions given to fix that, then close and reopen your shell. + +Then run the following command: + +.. code-block:: none + + CONFIGURE_OPTS=--enable-optimizations pyenv install 3.7.0 -v + +This may take a long time to complete. + +After that is finished, run: + +.. code-block:: none + + pyenv global 3.7.0 + +Pyenv is now installed and your system should be configured to run Python 3.7. + +~~~ +Mac +~~~ + +Install Brew: in Finder or Spotlight, search for and open *Terminal*. In the terminal, paste the +following, then press Enter: + +.. code-block:: none + + /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" + +After the installation, install the required packages by pasting the commands and pressing enter, +one-by-one: + +.. code-block:: none + + brew install python3 --with-brewed-openssl + brew install git + brew tap caskroom/versions + brew cask install java8 + +~~~~~~~~~~~~~~~~~~~~~~~~~~ +Ubuntu 18.04 Bionic Beaver +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: none + + sudo apt install python3.6-dev python3-pip build-essential libssl-dev libffi-dev git unzip default-jre -y + +~~~~~~~~~~~~~~~~~~~~~~~~~ +Ubuntu 16.04 Xenial Xerus +~~~~~~~~~~~~~~~~~~~~~~~~~ + +We recommend adding the ``deadsnakes`` apt repository to install Python 3.6 or greater: + +.. code-block:: none + + sudo apt install software-properties-common + sudo add-apt-repository ppa:deadsnakes/ppa + sudo apt update + +Now, install python, pip, git and java with the following commands: + +.. code-block:: none + + sudo apt install python3.6-dev build-essential libssl-dev libffi-dev git unzip default-jre wget -y + wget https://bootstrap.pypa.io/get-pip.py + sudo python3.6 get-pip.py + +------------------------------ +Creating a Virtual Environment +------------------------------ + +We **strongly** recommend installing Red into a virtual environment. See the section +`installing-in-virtual-environment`. + +.. _installing-red-linux-mac: + +-------------- +Installing Red +-------------- + +Choose one of the following commands to install Red. + +.. note:: + + If you're not inside an activated virtual environment, include the ``--user`` flag with all + ``pip3`` commands. + +To install without audio support: + +.. code-block:: none + + pip3 install -U --process-dependency-links --no-cache-dir Red-DiscordBot + +Or, to install with audio support: + +.. code-block:: none + + pip3 install -U --process-dependency-links --no-cache-dir Red-DiscordBot[voice] + +Or, install with audio and MongoDB support: + +.. code-block:: none + + pip3 install -U --process-dependency-links --no-cache-dir Red-DiscordBot[voice,mongo] + +.. note:: + + To install the development version, replace ``Red-DiscordBot`` in the above commands with the + following link: + + .. code-block:: none + + git+https://github.com/Cog-Creators/Red-DiscordBot@V3/develop#egg=Red-DiscordBot + +-------------------------- +Setting Up and Running Red +-------------------------- + +After installation, set up your instance with the following command: + +.. code-block:: none + + redbot-setup + +This will set the location where data will be stored, as well as your +storage backend and the name of the instance (which will be used for +running the bot). + +Once done setting up the instance, run the following command to run Red: + +.. code-block:: none + + redbot + +It will walk through the initial setup, asking for your token and a prefix. + +You may also run Red via the launcher, which allows you to restart the bot +from discord, and enable auto-restart. You may also update the bot from the +launcher menu. Use the following command to run the launcher: + +.. code-block:: none + + redbot-launcher + diff --git a/docs/install_mac.rst b/docs/install_mac.rst deleted file mode 100644 index 2cbb12af4..000000000 --- a/docs/install_mac.rst +++ /dev/null @@ -1,53 +0,0 @@ -.. mac install guide - -===================== -Installing Red on Mac -===================== - ---------------------------- -Installing pre-requirements ---------------------------- - -* Install Brew - * In Finder or Spotlight, search for and open terminal. In the window that will open, paste this: - :code:`/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"` - and press enter. -* After the installation, install the required packages by pasting the commands and pressing enter, one-by-one: - * :code:`brew install python3 --with-brewed-openssl` - * :code:`brew install git` - * :code:`brew tap caskroom/versions` - * :code:`brew cask install java8` - --------------- -Installing Red --------------- - -Without audio: - -:code:`pip3 install -U --process-dependency-links red-discordbot` - -With audio: - -:code:`pip3 install -U --process-dependency-links red-discordbot[voice]` - -To install the development version (without audio): - -:code:`pip3 install -U --process-dependency-links git+https://github.com/Cog-Creators/Red-DiscordBot@V3/develop#egg=red-discordbot` - -To install the development version (with audio): - -:code:`pip3 install -U --process-dependency-links git+https://github.com/Cog-Creators/Red-DiscordBot@V3/develop#egg=red-discordbot[voice]` - ----------------------- -Setting up an instance ----------------------- - -To set up an instance, run :code:`redbot-setup` and follow the steps there, providing the requested information -or accepting the defaults. Keep in mind that the instance name will be the one you use when running the bot, so -make it something you can remember - ------------ -Running Red ------------ - -Run :code:`redbot ` and go through the initial setup (it will ask for the token and a prefix). \ No newline at end of file diff --git a/docs/install_raspbian.rst b/docs/install_raspbian.rst deleted file mode 100644 index fd18a43d5..000000000 --- a/docs/install_raspbian.rst +++ /dev/null @@ -1,72 +0,0 @@ -.. raspbian install guide - -================================== -Installing Red on Raspbian Stretch -================================== - -.. warning:: For safety reasons, DO NOT install Red with a root user. Instead, `make a new one `_. - ---------------------------- -Installing pre-requirements ---------------------------- - -.. code-block:: none - - sudo apt install -y make build-essential libssl-dev zlib1g-dev libbz2-dev libreadline-dev libsqlite3-dev wget curl llvm libncurses5-dev libncursesw5-dev xz-utils tk-dev libffi-dev git unzip default-jre - curl -L https://github.com/pyenv/pyenv-installer/raw/master/bin/pyenv-installer | bash - -After that last command, you may see a warning about 'pyenv' not being in the load path. Follow the instructions given to fix that, then close and reopen your shell - -Then run the following command: - -.. code-block:: none - - CONFIGURE_OPTS=--enable-optimizations pyenv install 3.6.5 -v - -This may take a long time to complete. - -After that is finished, run: - -.. code-block:: none - - pyenv global 3.6.5 - --------------- -Installing Red --------------- - -Without audio: - -:code:`pip3 install -U --process-dependency-links red-discordbot --user` - -With audio: - -:code:`pip3 install -U --process-dependency-links red-discordbot[voice] --user` - -To install the development version (without audio): - -:code:`pip3 install -U --process-dependency-links git+https://github.com/Cog-Creators/Red-DiscordBot@V3/develop#egg=red-discordbot --user` - -To install the development version (with audio): - -:code:`pip3 install -U --process-dependency-links git+https://github.com/Cog-Creators/Red-DiscordBot@V3/develop#egg=red-discordbot[voice] --user` - ----------------------- -Setting up an instance ----------------------- - -Run :code:`redbot-setup` and follow the prompts. It will ask first for where you want to -store the data (the default is :code:`~/.local/share/Red-DiscordBot`) and will then ask -for confirmation of that selection. Next, it will ask you to choose your storage backend -(the default here is JSON). It will then ask for a name for your instance. This can be -anything as long as it does not contain spaces; however, keep in mind that this is the -name you will use to run your bot, and so it should be something you can remember. - ------------ -Running Red ------------ - -Run :code:`redbot ` and run through the initial setup. This will ask for -your token and a prefix. - -.. warning:: Audio will not work on Raspberry Pi's **below** 2B. This is a CPU problem and *cannot* be fixed. diff --git a/docs/install_ubuntu_bionic.rst b/docs/install_ubuntu_bionic.rst deleted file mode 100644 index b3eb4b0ec..000000000 --- a/docs/install_ubuntu_bionic.rst +++ /dev/null @@ -1,54 +0,0 @@ -.. ubuntu bionic install guide - -============================== -Installing Red on Ubuntu 18.04 -============================== - -.. warning:: For safety reasons, DO NOT install Red with a root user. Instead, `make a new one `_. - -------------------------------- -Installing the pre-requirements -------------------------------- - -.. code-block:: none - - sudo apt install python3.6-dev python3-pip build-essential libssl-dev libffi-dev git unzip default-jre -y - - ------------------- -Installing the bot ------------------- - -To install without audio: - -:code:`pip3 install -U --process-dependency-links red-discordbot --user` - -To install with audio: - -:code:`pip3 install -U --process-dependency-links red-discordbot[voice] --user` - -To install the development version (without audio): - -:code:`pip3 install -U --process-dependency-links git+https://github.com/Cog-Creators/Red-DiscordBot@V3/develop#egg=red-discordbot --user` - -To install the development version (with audio): - -:code:`pip3 install -U --process-dependency-links git+https://github.com/Cog-Creators/Red-DiscordBot@V3/develop#egg=red-discordbot[voice] --user` - ------------------------- -Setting up your instance ------------------------- - -Run :code:`redbot-setup` and follow the prompts. It will ask first for where you want to -store the data (the default is :code:`~/.local/share/Red-DiscordBot`) and will then ask -for confirmation of that selection. Next, it will ask you to choose your storage backend -(the default here is JSON). It will then ask for a name for your instance. This can be -anything as long as it does not contain spaces; however, keep in mind that this is the -name you will use to run your bot, and so it should be something you can remember. - ------------ -Running Red ------------ - -Run :code:`redbot ` and run through the initial setup. This will ask for -your token and a prefix. diff --git a/docs/install_ubuntu_xenial.rst b/docs/install_ubuntu_xenial.rst deleted file mode 100644 index 981b0bdf7..000000000 --- a/docs/install_ubuntu_xenial.rst +++ /dev/null @@ -1,59 +0,0 @@ -.. ubuntu xenial install guide - -============================== -Installing Red on Ubuntu 16.04 -============================== - -.. warning:: For safety reasons, DO NOT install Red with a root user. Instead, `make a new one `_. - -------------------------------- -Installing the pre-requirements -------------------------------- - -.. code-block:: none - - sudo apt install software-properties-common - sudo add-apt-repository ppa:deadsnakes/ppa - sudo apt update - sudo apt install python3.6-dev build-essential libssl-dev libffi-dev git unzip default-jre wget -y - wget https://bootstrap.pypa.io/get-pip.py - sudo python3.6 get-pip.py - - ------------------- -Installing the bot ------------------- - -To install without audio: - -:code:`pip3.6 install -U --process-dependency-links red-discordbot --user` - -To install with audio: - -:code:`pip3.6 install -U --process-dependency-links red-discordbot[voice] --user` - -To install the development version (without audio): - -:code:`pip3.6 install -U --process-dependency-links git+https://github.com/Cog-Creators/Red-DiscordBot@V3/develop#egg=red-discordbot --user` - -To install the development version (with audio): - -:code:`pip3.6 install -U --process-dependency-links git+https://github.com/Cog-Creators/Red-DiscordBot@V3/develop#egg=red-discordbot[voice] --user` - ------------------------- -Setting up your instance ------------------------- - -Run :code:`redbot-setup` and follow the prompts. It will ask first for where you want to -store the data (the default is :code:`~/.local/share/Red-DiscordBot`) and will then ask -for confirmation of that selection. Next, it will ask you to choose your storage backend -(the default here is JSON). It will then ask for a name for your instance. This can be -anything as long as it does not contain spaces; however, keep in mind that this is the -name you will use to run your bot, and so it should be something you can remember. - ------------ -Running Red ------------ - -Run :code:`redbot ` and run through the initial setup. This will ask for -your token and a prefix. diff --git a/docs/install_windows.rst b/docs/install_windows.rst index 11cd883f4..309a6dfd1 100644 --- a/docs/install_windows.rst +++ b/docs/install_windows.rst @@ -1,4 +1,4 @@ -.. windows installation docs +.. _windows-install-guide: ========================= Installing Red on Windows @@ -21,23 +21,74 @@ Needed Software .. attention:: Please choose the "Windows Online" installer +.. _installing-red-windows: + -------------- Installing Red -------------- 1. Open a command prompt (open Start, search for "command prompt", then click it) -2. Run the appropriate command, depending on if you want audio or not +2. Create and activate a virtual environment (strongly recommended), see the section `using-venv` +3. Run **one** of the following commands, depending on what extras you want installed - * No audio: :code:`python -m pip install -U --process-dependency-links Red-DiscordBot` - * Audio: :code:`python -m pip install -U --process-dependency-links Red-DiscordBot[voice]` - * Development version (without audio): :code:`python -m pip install -U --process-dependency-links git+https://github.com/Cog-Creators/Red-DiscordBot@V3/develop#egg=red-discordbot` - * Development version (with audio): :code:`python -m pip install -U --process-dependency-links git+https://github.com/Cog-Creators/Red-DiscordBot@V3/develop#egg=red-discordbot[voice]` + .. note:: -3. Once that has completed, run :code:`redbot-setup` to set up your instance + If you're not inside an activated virtual environment, include the ``--user`` flag with all + ``pip`` commands. - * This will set the location where data will be stored, as well as your - storage backend and the name of the instance (which will be used for - running the bot) + * No audio: -4. Once done setting up the instance, run :code:`redbot ` to run Red. - It will walk through the initial setup, asking for your token and a prefix + .. code-block:: none + + python -m pip install -U --process-dependency-links --no-cache-dir Red-DiscordBot + + * With audio: + + .. code-block:: none + + python -m pip install -U --process-dependency-links --no-cache-dir Red-DiscordBot[voice] + + * With audio and MongoDB support: + + .. code-block:: none + + python -m pip install -U --process-dependency-links --no-cache-dir Red-DiscordBot[voice,mongo] + + .. note:: + + To install the development version, replace ``Red-DiscordBot`` in the above commands with the + following link: + + .. code-block:: none + + git+https://github.com/Cog-Creators/Red-DiscordBot@V3/develop#egg=Red-DiscordBot + +-------------------------- +Setting Up and Running Red +-------------------------- + +After installation, set up your instance with the following command: + +.. code-block:: none + + redbot-setup + +This will set the location where data will be stored, as well as your +storage backend and the name of the instance (which will be used for +running the bot). + +Once done setting up the instance, run the following command to run Red: + +.. code-block:: none + + redbot + +It will walk through the initial setup, asking for your token and a prefix. + +You may also run Red via the launcher, which allows you to restart the bot +from discord, and enable auto-restart. You may also update the bot from the +launcher menu. Use the following command to run the launcher: + +.. code-block:: none + + redbot-launcher diff --git a/docs/venv_guide.rst b/docs/venv_guide.rst new file mode 100644 index 000000000..fbeddaeb2 --- /dev/null +++ b/docs/venv_guide.rst @@ -0,0 +1,132 @@ +.. _installing-in-virtual-environment: + +======================================= +Installing Red in a Virtual Environment +======================================= +Virtual environments allow you to isolate red's library dependencies, cog dependencies and python +binaries from the rest of your system. It is strongly recommended you use this if you use python +for more than just Red. + +.. _using-venv: + +-------------- +Using ``venv`` +-------------- +This is the quickest way to get your virtual environment up and running, as `venv` is shipped with +python. + +First, choose a directory where you would like to create your virtual environment. It's a good idea +to keep it in a location which is easy to type out the path to. From now, we'll call it +``path/to/venv/`` (or ``path\to\venv\`` on Windows). + +~~~~~~~~~~~~~~~~~~~~~~~~ +``venv`` on Linux or Mac +~~~~~~~~~~~~~~~~~~~~~~~~ +Create your virtual environment with the following command:: + + python3 -m venv path/to/venv/ + +And activate it with the following command:: + + source path/to/venv/bin/activate + +.. important:: + + You must activate the virtual environment with the above command every time you open a new + shell to run, install or update Red. + +Continue reading `below `. + +~~~~~~~~~~~~~~~~~~~ +``venv`` on Windows +~~~~~~~~~~~~~~~~~~~ +Create your virtual environment with the following command:: + + python -m venv path\to\venv\ + +And activate it with the following command:: + + path\to\venv\Scripts\activate.bat + +.. important:: + + You must activate the virtual environment with the above command every time you open a new + Command Prompt to run, install or update Red. + +Continue reading `below `. + +.. _using-pyenv-virtualenv: + +-------------------------- +Using ``pyenv virtualenv`` +-------------------------- + +.. note:: + + This is for non-Windows users only. + +Using ``pyenv virtualenv`` saves you the headache of remembering where you installed your virtual +environments. If you haven't already, install pyenv with `pyenv-installer`_. + +First, ensure your pyenv interpreter is set to python 3.6 or later with the following command:: + + pyenv version + +Now, create a virtual environment with the following command:: + + pyenv virtualenv + +Replace ```` with whatever you like. If you forget what you named it, use the command ``pyenv +versions``. + +Now activate your virtualenv with the following command:: + + pyenv shell + +.. important:: + + You must activate the virtual environment with the above command every time you open a new + shell to run, install or update Red. + +Continue reading `below `. + +.. _pyenv-installer: https://github.com/pyenv/pyenv-installer/blob/master/README.rst + +---- + +.. _after-activating-virtual-environment: + +Once activated, your ``PATH`` environment variable will be modified to use the virtual +environment's python executables, as well as other executables like ``pip``. + +From here, install Red using the commands listed on your installation guide (`Windows +` or `Non-Windows `). + +.. note:: + + The alternative to activating the virtual environment each time you open a new shell is to + provide the full path to the executable. This will automatically use the virtual environment's + python interpreter and installed libraries. + +-------------------------------------------- +Virtual Environments with Multiple Instances +-------------------------------------------- +If you are running multiple instances of Red on the same machine, you have the option of either +using the same virtual environment for all of them, or creating separate ones. + +.. note:: + + This only applies for multiple instances of V3. If you are running a V2 instance as well, + You **must** use separate virtual environments. + +The advantages of using a *single* virtual environment for all of your V3 instances are: + +- When updating Red, you will only need to update it once for all instances (however you will still need to restart all instances for the changes to take effect) +- It will save space on your hard drive + +On the other hand, you may wish to update each of your instances individually. + +.. important:: + + Windows users with multiple instances should create *separate* virtual environments, as + updating multiple running instances at once is likely to cause errors.