-
-
Notifications
You must be signed in to change notification settings - Fork 46
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
[TASK] Rework the installation manuals.
- Loading branch information
Showing
8 changed files
with
272 additions
and
206 deletions.
There are no files selected for viewing
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,8 +1,13 @@ | ||
|
||
=============== | ||
Getting Started | ||
=============== | ||
============================== | ||
Getting Started (installation) | ||
============================== | ||
|
||
.. include:: installation.rst | ||
.. include:: configuration.rst | ||
.. include:: starting.rst | ||
.. toctree:: | ||
:glob: | ||
:maxdepth: 1 | ||
|
||
requirements | ||
installation-linux | ||
installation-windows | ||
starting |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,140 @@ | ||
|
||
Installation on Linux | ||
--------------------- | ||
|
||
.. contents:: | ||
|
||
|
||
1. Operating System needs | ||
~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
|
||
PyPlanet requires Python 3.5 and later. We also require to have some operating system libraries and build tools installed. | ||
We will guide you through the steps that are required to install those requirements in this subtopic. | ||
|
||
Debian / Ubuntu | ||
``````````````` | ||
|
||
Install the operating system requirements by executing the following commands: | ||
|
||
``sudo apt-get update && apt-get install build-essential libssl-dev libffi-dev python3-dev zlib1g-dev`` | ||
|
||
Fedora / RHEL based | ||
``````````````````` | ||
|
||
Install the operating system requirements by executing the following commands: | ||
|
||
``sudo yum install gcc libffi-devel python3-devel openssl-devel zlib``. | ||
|
||
|
||
2. Install PyEnv and Python | ||
~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
|
||
To make things as easy as possible we are going to use `PyEnv`. It's a tool that will install Python for you with | ||
all the requirements and also manage to adjust the environment we are running in. | ||
|
||
The following steps are the same for all distributions. | ||
|
||
.. note:: | ||
|
||
Make sure you are logged in as the user that is going to run PyPlanet. (Mostly not root!). | ||
|
||
|
||
**Install PyEnv** | ||
|
||
.. code-block:: bash | ||
curl -L https://raw.githubusercontent.com/pyenv/pyenv-installer/master/bin/pyenv-installer | bash | ||
printf '\nexport PATH="$HOME/.pyenv/bin:$PATH"\neval "$(pyenv init -)"\neval "$(pyenv virtualenv-init -)"\n' >> ~/.bashrc | ||
source ~/.bashrc | ||
**Install Python** | ||
|
||
.. code-block:: bash | ||
pyenv install 3.6.1 | ||
pyenv global 3.6.1 | ||
.. attention:: | ||
|
||
The first set of commands makes adjustments to the ``~/.bashrc`` file. It can be that you don't have this file installed. | ||
|
||
If that is the case, you can add those lines manually to any other script that is executed when you open your shell (``.profile``) | ||
or execute these commands manually at every start of a SSH session. Your SSH session might have to be restarted after this change! | ||
|
||
.. code-block:: bash | ||
export PATH="~/.pyenv/bin:$PATH" | ||
eval "$(pyenv init -)" | ||
eval "$(pyenv virtualenv-init -)" | ||
.. _step-3-ref: | ||
|
||
3. Create environment for your installation | ||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
|
||
We recommend to separate multiple installations by creating a so called virtual environment. This will make sure you can | ||
run several PyPlanet and dependency versions on the same Python installation. You can skip this step if you don't want to | ||
use virtual environments, but we recommend to use it. | ||
|
||
**Create virtualenv**: | ||
|
||
.. code-block:: bash | ||
pyenv virtualenv 3.6.1 pyplanet | ||
# Where 'pyplanet' is your environment name, you need adjust this if you have multiple installations. | ||
**Activate virtualenv**: | ||
|
||
.. note:: | ||
|
||
You have to activate your virtual environment **every time** you want to execute PyPlanet commands! That means that you have | ||
to activate before you update, start, develop and do anything with PyPlanet! | ||
|
||
.. code-block:: bash | ||
pyenv activate pyplanet | ||
# Where 'pyplanet' is your environment name, you need adjust this if you have multiple installations. | ||
4. PyPlanet Installation | ||
~~~~~~~~~~~~~~~~~~~~~~~~ | ||
|
||
PyPlanet is published through the Python Package Index (PyPi) and is easy to install with ``pip``. | ||
|
||
.. code-block:: bash | ||
pip install pyplanet --upgrade | ||
After installing it on your system you can use the pyplanet cli commands. To get help about commands, use ``pyplanet help``. | ||
|
||
5. Setup Project | ||
~~~~~~~~~~~~~~~~ | ||
|
||
After installing PyPlanet on your system, you can't yet start any instances because starting requires you to give up an | ||
settings module. You could either provide this with the start command or create a project directory with skeleton files. | ||
|
||
We recommend using the ``init_project`` command to create a local project installation where you can install apps, keep | ||
PyPlanet and it's apps up-to-date, provide settings through a useful settings module and provide ``manage.py`` as a wrapper | ||
so you never have to manually provide your settings module. | ||
|
||
In the example bellow we will setup a project with the name `canyon_server`. The folder `canyon_server` will be created | ||
and skeleton files will be copied. | ||
|
||
.. code-block:: bash | ||
pyplanet init_project canyon_server | ||
After setup your project, you have to install or update your dependencies from your local ``requirements.txt``. | ||
|
||
To upgrade your existing installation, see our :doc:`Upgrading Guide </intro/upgrading>`. | ||
|
||
.. warning:: | ||
|
||
If you use the virtual environment we installed in :ref:`step-3-ref`, make sure you activate it **before you install or update dependencies**! | ||
|
||
|
||
**Head to the next step** | ||
|
||
Configure your PyPlanet installation now by going to the next chapter: :doc:`/intro/configuration`. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,97 @@ | ||
|
||
Installation on Windows | ||
----------------------- | ||
|
||
.. contents:: | ||
|
||
|
||
1. Installing Python | ||
~~~~~~~~~~~~~~~~~~~~ | ||
|
||
If you have not yet installed Python 3.5 or later on your Windows machine, do it now by going to the following link: | ||
|
||
https://www.python.org/downloads/release/python-361/ | ||
|
||
Head towards the end of the page and click on the `Windows x86-64 executable installer` link. After starting the executable | ||
you will get an wizard. | ||
|
||
Make sure it looks like this and click on the red area to continue. | ||
|
||
|
||
.. figure:: /_static/intro/python-windows-1.png | ||
:alt: Setup wizard with the required settings | ||
|
||
Setup wizard with the checkboxes enabled. | ||
|
||
.. note:: | ||
|
||
Make sure you checked the two checkboxes: `Install launcher for all users` and `Add Python to PATH`. | ||
|
||
|
||
2. Creating Virtual Environment | ||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
|
||
To prevent the usage of the administration leverage and to benefit from multiple PyPlanet installations and a clean environment | ||
we recommend to setup a Virtual Environment. | ||
|
||
Do this by going to your directory where you want to setup the PyPlanet installation. Create a folder somewhere that is empty and ready | ||
for the PyPlanet settings and other files. | ||
|
||
Open a terminal in this folder by holding :kbd:`SHIFT` and :kbd:`Right click` on an empty space in the folder. Then click ``Open terminal here``. | ||
|
||
In the terminal, type the following command to create the environment: | ||
|
||
.. code-block:: bash | ||
virtualenv env | ||
From now you have to activate the virtualenv, every time you want to execute operations with PyPlanet (such as starting, installing, updating, etc). | ||
To activate, use the following commands: | ||
|
||
.. code-block:: bash | ||
# Windows, in your command prompt | ||
env\Scripts\activate.bat | ||
3. PyPlanet Installation | ||
~~~~~~~~~~~~~~~~~~~~~~~~ | ||
|
||
PyPlanet is published through the Python Package Index (PyPi) and is easy to install with the ``pip`` commands. | ||
|
||
.. code-block:: bash | ||
pip install pyplanet --upgrade | ||
After installing it on your system you can use the pyplanet cli commands. To get help about commands, use ``pyplanet help``. | ||
|
||
4. Setup Project | ||
~~~~~~~~~~~~~~~~ | ||
|
||
After installing PyPlanet on your system, you can't yet start any instances because starting requires you to give up an | ||
settings module. You could either provide this with the start command or create a project directory with skeleton files. | ||
|
||
We recommend using the ``init_project`` command to create a local project installation where you can install apps, keep | ||
PyPlanet and it's apps up-to-date, provide settings through a useful settings module and provide ``manage.py`` as a wrapper | ||
so you never have to manually provide your settings module. | ||
|
||
Because you have created an Virtual Environment earlier you want to store your 'project' in the same folder. You can do this | ||
with the following command: | ||
|
||
.. code-block:: bash | ||
pyplanet init_project . | ||
After setup your project, you have to install or update your dependencies from your local ``requirements.txt``. | ||
|
||
To upgrade your existing installation, see our :doc:`Upgrading Guide </intro/upgrading>`. | ||
|
||
.. warning:: | ||
|
||
If you use the virtual environment we installed in :ref:`step-3-ref`, make sure you activate it **before you install or update dependencies**! | ||
|
||
|
||
**Head to the next step** | ||
|
||
Configure your PyPlanet installation now by going to the next chapter: :doc:`/intro/configuration`. |
Oops, something went wrong.