Skip to content
Permalink
Browse files

[Docs] Update linux install docs, redo venv docs (#2920)

* [Docs] Update linux install docs, redo venv docs

Some of our pre-req installation docs needed updating on Windows - this adds new sections for Fedora Linux and Debian/Raspbian Buster, and also removes some unnecessary pre-requirements from other distributions. These have all been tested on fresh VPSes, installing Red both in venvs and with --user, and they all seem to work.

Also, apparently the venv docs were too scary before. These changes try to make it clear that it's easier to use than users may think.

This also includes a little note to stop users from accidentally installing Python with pyenv after installing pre-requirements on Ubuntu.

Signed-off-by: Toby Harradine <tobyharradine@gmail.com>

* Add changelog entries

Signed-off-by: Toby Harradine <tobyharradine@gmail.com>

* Update officially supported platforms in README.md

Signed-off-by: Toby Harradine <tobyharradine@gmail.com>

* Combine sections and add openSUSE

Signed-off-by: Toby Harradine <tobyharradine@gmail.com>

* Include example of using `--user` flag

Signed-off-by: Toby Harradine <tobyharradine@gmail.com>

* Use `py -3.7` on Windows outside of venv

Signed-off-by: Toby Harradine <tobyharradine@gmail.com>

* Reorganise changelog entries

Signed-off-by: Toby Harradine <tobyharradine@gmail.com>
  • Loading branch information...
Tobotimus authored and mikeshardmind committed Aug 30, 2019
1 parent d9e774f commit 25fb389a7d7cbb99ef3ed7e882192f1043682f9b
Showing with 153 additions and 60 deletions.
  1. +1 −6 README.md
  2. +1 −0 changelog.d/2558.docs.rst
  3. +1 −0 changelog.d/2920.docs.rst
  4. +119 −42 docs/install_linux_mac.rst
  5. +8 −4 docs/install_windows.rst
  6. +23 −8 docs/venv_guide.rst
@@ -85,12 +85,7 @@ community of cog repositories.**

- [Windows](https://red-discordbot.readthedocs.io/en/stable/install_windows.html)
- [MacOS](https://red-discordbot.readthedocs.io/en/stable/install_linux_mac.html)
- [Ubuntu](https://red-discordbot.readthedocs.io/en/stable/install_linux_mac.html)
- [Debian Stretch](https://red-discordbot.readthedocs.io/en/stable/install_linux_mac.html)
- [CentOS 7](https://red-discordbot.readthedocs.io/en/stable/install_linux_mac.html)
- [Arch Linux](https://red-discordbot.readthedocs.io/en/stable/install_linux_mac.html)
- [Raspbian Stretch](https://red-discordbot.readthedocs.io/en/stable/install_linux_mac.html)

- [Most major linux distributions](https://red-discordbot.readthedocs.io/en/stable/install_linux_mac.html)

If after reading the guide you are still experiencing issues, feel free to join the
[Official Discord Server](https://discord.gg/red) and ask in the **#support** channel for help.
@@ -0,0 +1 @@
Updated linux install docs, adding sections for Fedora Linux, Debian/Raspbian Buster, and openSUSE.
@@ -0,0 +1 @@
Reworded virtual environment guide to make it sound less scary.
@@ -7,7 +7,8 @@ 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.
a new user on Linux, see `this guide by DigitalOcean
<https://www.digitalocean.com/community/tutorials/how-to-create-a-sudo-user-on-ubuntu-quickstart>`_.

-------------------------------
Installing the pre-requirements
@@ -21,6 +22,9 @@ The pre-requirements are:
- git
- Java Runtime Environment 8 or later (for audio support)

We also recommend installing some basic compiler tools, in case our dependencies don't provide
pre-built "wheels" for your architecture.

.. _install-arch:

~~~~~~~~~~
@@ -29,48 +33,71 @@ Arch Linux

.. code-block:: none

sudo pacman -Syu python-pip git base-devel jre8-openjdk
sudo pacman -Syu python python-pip git jre-openjdk-headless base-devel

.. _install-centos:
.. _install-fedora:
.. _install-rhel:

~~~~~~~~~~~~~~~~~~~~~~~~~~
CentOS 7, Fedora, and RHEL
~~~~~~~~~~~~~~~~~~~~~~~~~~
~~~~~~~~~~~~~~~~~
CentOS and RHEL 7
~~~~~~~~~~~~~~~~~

.. code-block:: none

yum -y groupinstall development
yum -y install https://centos7.iuscommunity.org/ius-release.rpm
sudo yum install zlib-devel bzip2 bzip2-devel readline-devel sqlite sqlite-devel \
openssl-devel xz xz-devel libffi-devel git2u java-1.8.0-openjdk
openssl-devel xz xz-devel libffi-devel findutils git2u java-1.8.0-openjdk

Complete the rest of the installation by `installing Python 3.7 with pyenv <install-python-pyenv>`.

.. _install-debian:
.. _install-raspbian:

~~~~~~~~~~~~~~~~~~~~~~~~~~~
Debian and Raspbian Stretch
~~~~~~~~~~~~~~~~~~~~~~~~~~~
~~~~~~~~~~~~~~~~~~~
Debian and Raspbian
~~~~~~~~~~~~~~~~~~~

.. warning::
Debian and Raspbian Buster
**************************

Debian and Raspbian Buster have all required packages available in official repositories. Install
them with apt:

.. code-block:: none

sudo apt update
sudo apt install python3 python3-dev python3-venv python3-pip git default-jre-headless \
build-essential

Audio will not work on Raspberry Pi's **below** 2B. This is a CPU problem and
*cannot* be fixed.
Debian and Raspbian Stretch
***************************

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 liblzma-dev python3-openssl git unzip default-jre
sudo apt update
sudo apt install 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 \
liblzma-dev python3-openssl git default-jre-headless

Complete the rest of the installation by `installing Python 3.7 with pyenv <install-python-pyenv>`.

.. _install-fedora:

~~~~~~~~~~~~
Fedora Linux
~~~~~~~~~~~~

Fedora Linux 29 and above has all required packages available in official repositories. Install
them with dnf:

.. code-block:: none

sudo dnf install python3 python3-devel git java-latest-openjdk-headless @development-tools

.. _install-mac:

~~~
@@ -94,49 +121,95 @@ one-by-one:
brew tap caskroom/versions
brew cask install homebrew/cask-versions/adoptopenjdk8

It's possible you will have network issues. If so, go in your Applications folder, inside it, go in the Python 3.7 folder then double click ``Install certificates.command``
It's possible you will have network issues. If so, go in your Applications folder, inside it, go in
the Python 3.7 folder then double click ``Install certificates.command``.

.. _install-ubuntu:
.. _install-ubuntu-bionic:
.. _install-ubuntu-cosmic:
.. _install-opensuse:

~~~~~~~~
openSUSE
~~~~~~~~

openSUSE Leap
*************

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Ubuntu 18.04 Bionic Beaver and 18.10 Cosmic Cuttlefish
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
We recommend installing a community package to get Python 3.7 on openSUSE Leap. This package will
be installed to the ``/opt`` directory.

First, add the Opt-Python community repository:

.. code-block:: none

sudo apt install python3.7 python3.7-dev python3.7-venv python3-pip build-essential \
libssl-dev libffi-dev git unzip default-jre -y
source /etc/os-release
sudo zypper ar -f https://download.opensuse.org/repositories/home:/Rotkraut:/Opt-Python/openSUSE_Leap_${VERSION_ID}/ Opt-Python

Now install the pre-requirements with zypper:

.. _install-ubuntu-xenial:
.. code-block:: none

~~~~~~~~~~~~~~~~~~~~~~~~~
Ubuntu 16.04 Xenial Xerus
~~~~~~~~~~~~~~~~~~~~~~~~~
sudo zypper install opt-python37 opt-python37-setuptools git-core java-11-openjdk-headless
sudo zypper install -t pattern devel_basis

We recommend adding the ``deadsnakes`` apt repository to install Python 3.7 or greater:
Since Python is now installed to ``/opt/python``, we should add it to PATH. You can add a file in
``/etc/profile.d/`` to do this:

.. code-block:: none

sudo apt install software-properties-common
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt update
echo 'export PATH="/opt/python/bin:$PATH"' | sudo tee /etc/profile.d/opt-python.sh
source /etc/profile.d/opt-python.sh

Now, install pip with easy_install:

.. code-block:: none

sudo /opt/python/bin/easy_install-3.7 pip

openSUSE Tumbleweed
*******************

Now, install python, pip, git and java with the following commands:
openSUSE Tumbleweed has all required dependencies available in official repositories. Install them
with zypper:

.. code-block:: none

sudo apt install python3.7 python3.7-dev build-essential libssl-dev libffi-dev git \
unzip default-jre curl -y
curl https://bootstrap.pypa.io/get-pip.py | sudo python3.7
sudo zypper install python3-base python3-pip git-core java-12-openjdk-headless
sudo zypper install -t pattern devel_basis

.. _install-ubuntu:

~~~~~~
Ubuntu
~~~~~~

.. note:: **Ubuntu 16.04 Users**

You must add a 3rd-party repository to install Python 3.7 on Ubuntu 16.04 with apt. We
recommend the ``deadsnakes`` repository:

.. code-block:: none

sudo apt install software-properties-common
sudo add-apt-repository ppa:deadsnakes/ppa

Install the pre-requirements with apt:

.. code-block:: none

sudo apt update
sudo apt install python3.7 python3.7-dev python3.7-venv python3-pip git default-jre-headless \
build-essential

.. _install-python-pyenv:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Installing Python with pyenv
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. note::

If you followed one of the sections above, and weren't linked here afterwards, you should skip
this section.

On distributions where Python 3.7 needs to be compiled from source, we recommend the use of pyenv.
This simplifies the compilation process and has the added bonus of simplifying setting up Red in a
virtual environment.
@@ -152,7 +225,7 @@ Then run the following command:

.. code-block:: none

CONFIGURE_OPTS=--enable-optimizations pyenv install 3.7.2 -v
CONFIGURE_OPTS=--enable-optimizations pyenv install 3.7.4 -v

This may take a long time to complete, depending on your hardware. For some machines (such as
Raspberry Pis and micro-tier VPSes), it may take over an hour; in this case, you may wish to remove
@@ -164,16 +237,16 @@ After that is finished, run:

.. code-block:: none

pyenv global 3.7.2
pyenv global 3.7.4

Pyenv is now installed and your system should be configured to run Python 3.7.

------------------------------
Creating a Virtual Environment
------------------------------

We **strongly** recommend installing Red into a virtual environment. See the section
`installing-in-virtual-environment`.
We **strongly** recommend installing Red into a virtual environment. Don't be scared, it's very
straightforward. See the section `installing-in-virtual-environment`.

.. _installing-red-linux-mac:

@@ -186,7 +259,11 @@ 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
``python3.7 -m pip`` commands.
``python3.7 -m pip install`` commands, like this:

.. code-block:: none

python3.7 -m pip install --user -U Red-DiscordBot

To install without MongoDB support:

@@ -36,8 +36,8 @@ Manually installing dependencies

* `Python <https://www.python.org/downloads/>`_ - Red needs Python 3.7.0 or greater

.. note:: Please make sure that the box to add Python to PATH is CHECKED, otherwise
you may run into issues when trying to run Red.
.. attention:: Please make sure that the box to add Python to PATH is CHECKED, otherwise
you may run into issues when trying to run Red.

* `Git <https://git-scm.com/download/win>`_

@@ -62,8 +62,12 @@ Installing Red

.. note::

If you're not inside an activated virtual environment, include the ``--user`` flag with all
``pip`` commands.
If you're not inside an activated virtual environment, use ``py -3.7`` in place of
``python``, and include the ``--user`` flag with all ``pip install`` commands, like this:

.. code-block:: none

py -3.7 -m pip install --user -U Red-DiscordBot

* Normal installation:

@@ -3,9 +3,23 @@
=======================================
Installing Red in a Virtual Environment
=======================================
Creating a virtual environment is really easy and usually prevents many common installation
problems. Firstly, simply choose how you'd like to create your virtual environment:

* :ref:`using-venv` (quick and easy, involves two commands)
* :ref:`using-pyenv-virtualenv` (recommended if you installed Python with pyenv)

**Why Should I Use a Virtual Environment?**

90% of the installation and setup issues raised in our support channels are resolved when the user
creates a virtual environment.

**What Are Virtual Environments For?**

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.
binaries from the rest of your system. It also makes sure Red and its dependencies are installed to
a predictable location. It makes uninstalling Red as simple as removing a single folder, without
worrying about losing your data or other things on your system becoming broken.

.. _using-venv:

@@ -17,18 +31,18 @@ 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).
``redenv``.

~~~~~~~~~~~~~~~~~~~~~~~~
``venv`` on Linux or Mac
~~~~~~~~~~~~~~~~~~~~~~~~
Create your virtual environment with the following command::

python3.7 -m venv path/to/venv/
python3.7 -m venv redenv

And activate it with the following command::

source path/to/venv/bin/activate
source redenv/bin/activate

.. important::

@@ -42,11 +56,11 @@ Continue reading `below <after-activating-virtual-environment>`.
~~~~~~~~~~~~~~~~~~~
Create your virtual environment with the following command::

python -m venv path\to\venv\
py -3.7 -m venv redenv

And activate it with the following command::

path\to\venv\Scripts\activate.bat
redenv\Scripts\activate.bat

.. important::

@@ -86,7 +100,8 @@ Now activate your virtualenv with the following command::
.. important::

You must activate the virtual environment with the above command every time you open a new
shell to run, install or update Red.
shell to run, install or update Red. You can check out other commands like ``pyenv local`` and
``pyenv global`` if you wish to keep the virtualenv activated all the time.

Continue reading `below <after-activating-virtual-environment>`.

0 comments on commit 25fb389

Please sign in to comment.
You can’t perform that action at this time.