Requirements
Since a PAGoDA instance relies on many components, before working on PAGoDA or deploying it, you must ensure you fulfill some requirements. In this section we will describe requirements needed to either deploy or develop a PAGoDA instance, mainly for administrator or developers.
For the time being, user requirements are null as user interface (CLI and WebUI) are not ready. Moreover, user requirements will be described in dedicated user documentation
User Documentation (TODO)
User documentation is not ready yet.
This link will be updated when documentation will be ready.
In this section, we will consider two types of requirements:
- Software requirements The software required to either deploy or develop a PAGoDA instance.
- Hardware requirements The hardware required to support PAGoDA.
For each kind of requirement, we will also distinguish two sub-kinds of requirements:
- Local requirements: the requirements that a PAGoDA instance administrator or PAGoDA developer will need to fulfill for his (desktop) computer.
- Server requirements: the requirements needed on the servers that will host a PAGoDA instance.
Before listing the requirements, some further warning is needed:
- the development of PAGoDA was done on Ubuntu 18.04 and 20.04. The installation instructions provided for local software installation are thus ONLY available for those OSes (Ubuntu 18.04 and 20.04).
- the servers used as hosts during the PAGoDA development were running under Centos7. The server side software installation scripts/commands are thus ONLY provided for the Centos7 OS.
If your setup happens to be different from the above environments then the installation commands might require some OS adaptation work for which the PAGoDA documentation nevertheless provides some useful links.
Feel free to propose a merge request to add documentation about your operating system (refer to Contributing).
Software requirements
Local software requirements
In order to be able to deploy a PAGoDA instance or to develop PAGoDA, you will need the following software to be installed on your computer:
- python3 >= 3.8 The python programming language interpreter1
- pip3 The package installer for Python
- python3-venv Python virtual environment creator
- direnv (OPTIONAL) Allows to automatically load/unload the environment (handling virtualenv and others) encountered in the the current working directory.
With the above softwares, you should be able to install further local dependencies.
Indeed, most PAGoDA repositories come with a requirements.txt
file which
provides a list of python dependencies that are required in order to setup a
PAGoDA production instance. If you are a developer, you will further need the
requirements.dev.txt
file that is provided in PAGoDA repositories.
The main dependencies that will be installed with pip3
are (this list is not
exhaustive):
- python-openstackclient OpenStack Command-Line Client
- dnspython DNS toolkit
- openshift Openshift python client
- pyhelm Python binding for Helm: Kubernetes package manager
- grpcio HTTP/2-based RPC framework (required by pyhelm)
- molecule Molecule aids in the development and testing of Ansible roles
- ansible Radically simple IT automation
- docker A python library for the Docker Engine API
- mkdocs A markdown project documentation
- kubectl Kubernetes binary
- heml The package manager for Kubernetes
Most of the above requirement are required for Ansible Roles and to render documentation.
Here is a quick exemple of how to install the main dependencies into an Ubuntu 18.04 or 20.04. More details are given in section Installation and Configuration.
Installation of python3
Normally, python3
should already be installed in your Ubuntu 18.04 or 20.04.
To ensure this, type the following command:
python3 --version
# or
python3 -V
You should see this output:
Python 3.8.2
You might also have several version of Python installed on your system. The following command will help you get a list of all Python version you have:
apt list --installed | grep python
The output should be close to this one:
WARNING: apt does not have a stable CLI interface. Use with caution in scripts.
dh-python/bionic,bionic,now 3.20180325ubuntu2 all [installed,automatic]
libboost-python1.65.1/bionic,now 1.65.1+dfsg-0ubuntu5 amd64 [installed,automatic]
libpython-all-dev/bionic,now 2.7.15~rc1-1 amd64 [installed,automatic]
libpython-dev/bionic,now 2.7.15~rc1-1 amd64 [installed,automatic]
libpython-stdlib/bionic,now 2.7.15~rc1-1 amd64 [installed,automatic]
libpython2.7/bionic-security,bionic-updates,now 2.7.15-4ubuntu4~18.04 amd64 [installed]
libpython2.7-dev/bionic-security,bionic-updates,now 2.7.15-4ubuntu4~18.04 amd64 [installed,automatic]
libpython2.7-minimal/bionic-security,bionic-updates,now 2.7.15-4ubuntu4~18.04 amd64 [installed]
libpython2.7-stdlib/bionic-security,bionic-updates,now 2.7.15-4ubuntu4~18.04 amd64 [installed]
libpython3-dev/bionic-updates,now 3.6.7-1~18.04 amd64 [installed,automatic]
libpython3-stdlib/bionic-updates,now 3.6.7-1~18.04 amd64 [installed]
libpython3.6/bionic-security,bionic-updates,now 3.6.8-1~18.04.1 amd64 [installed]
libpython3.6-dev/bionic-security,bionic-updates,now 3.6.8-1~18.04.1 amd64 [installed,automatic]
libpython3.6-minimal/bionic-security,bionic-updates,now 3.6.8-1~18.04.1 amd64 [installed]
libpython3.6-stdlib/bionic-security,bionic-updates,now 3.6.8-1~18.04.1 amd64 [installed]
python/bionic,now 2.7.15~rc1-1 amd64 [installed]
If you do not have python3 installed on your system, the following commands will help you to install it:
# First update list of repositories
sudo apt-get update
# Second install python3
sudo apt-get install python3
The system might ask you the password for sudo as only authorized user can add/remove/upgrade software on Ubuntu. This documentation assume you are an authorized user.
If you want to go further, like installing python from its source or install it on other platform, you can see the following link
REMARK: On Ubuntu <= 18.04, you will not be able to have python 3.8 directly from the official repo. To install python 3.8 on these distributions, please refer to this documentation.
Installation of pip3
Once python3
is installed, you must ensure that pip3
is installed too.
To check it, you can type the following command:
pip --version
# or
pip -V
The output should be like the following, your version might change from the example below:
pip 20.0.2 from /usr/local/lib/python3/dist-packages/pip (python 3.8)
If it is not the case, this means that pip3
is not installed on your system.
To install it on Ubuntu 18.04 or 20.04, type the following command:
sudo apt-get install python3-pip
As mentioned before, you might be asked for the sudo password to ensure you are an authorized user.
It's possible that the pip3
version from the python3-pip
package is not
the last version of pip3
. To upgrade pip3
to its last version, type the
following command:
sudo pip3 install --upgrade pip
Finally, type again the command to check the version of pip3
to ensure you
installed the last version.
Installation of python3-venv
Since most of PAGoDA repositories use python, they relies on python virtual environment. If you are accustomed with the usage of python virtual environment, you might wish to skip the rest of the chapter.
If you are new to virtual environments, we recommend you to use
python3-venv
in order to manage your python virtual environments.
First ensure python3-venv
is already installed with the following command:
python3 -m venv -h
If python3-venv
is already installed, you should have the following
output:
usage: venv [-h] [--system-site-packages] [--symlinks | --copies] [--clear] [--upgrade] [--without-pip]
[--prompt PROMPT]
ENV_DIR [ENV_DIR ...]
Creates virtual Python environments in one or more target directories.
...
If you do not have python3-venv installed on your system, the following commands will help you to install it:
# First update list of repos
sudo apt-get update
# Second install python3-venv
sudo apt-get install python3-venv
As mentioned before, you might be asked for the sudo password to ensure you are an authorized user.
Finally, type again the command to check the version of python3-venv to ensure you installed the last version.
(OPTIONAL) Installation of direnv
Direnv
is a tool to automate the loading/unloading of a environment
variables (shell terminology) when entering some specific folders.
This can be applied to automatically load python virtual environment
when entering a python dedicated folder (for instance).
First check if direnv
is installed on your computer with the following
command:
direnv --version
The output should be similar to the following:
2.21.2
If you do not have direnv
installed on your system, the
following commands will help you to install it:
# First update list of repos
sudo apt-get update
# Second install direnv
sudo apt-get install direnv
As mentioned before, you might be asked for the sudo password to ensure you are an authorized user.
Then, type again the command to check the version of direnv to ensure you installed the last version.
Once direnv
is installed, you will need to add a direnv hook
to
your so-called shell rc file (e.g. ~/.shellrc
or ~/.bashrc
) to allow
direnv
to work properly. Please refer to direnv hook
documentation.
After this, you should be ready to setup your working environment and install all dependencies of each respective PAGoDA repository.
Distant software requirements
A PAGoDA instance relies on "distant" servers, for which we chose to only use Centos7 as Operating System on those servers. Distant software requirement will thus focus on Centos7.
For the time being, the PAGoDA project was not tested when starting out of Bare Metal hardware but only with cloud managed hardware. So, we will assume that you have access to an IaaS, in our case, which has to be OpenStack (since only OpenStack is currently supported).
Then, you must ensure the following :
- You have an SSH access to your servers
- Those SSH access can be done using an SSH key as an authentication credential (although this is not a strict requirement it will greatly facilitate the process of development or deployment).
Because ssh access depends on your Cloud Provider, and in order for you to learn how to assert for authentication requirements, you should pick the documentation section that corresponds to your technical context among the following ones:
Hardware requirements
Local hardware requirements
If you are an administrator who only needs to deploy a PAGoDA Instance, there is no specific hardware required. If you are a developer, your hardware must be able to run docker containers used for local testing purpose. Thus the following hardware configuration summarizes the minimum requirement:
- CPU with virtualization options activated
- At least 8Go of RAM
- An hard drive of at least 100Go (just in case you will need to download quite many docker images)
Distant hardware requirements
TBD once the release of PAGoDA v1.0 will be effective.
As a source of information while we define more explicit distant hardware requirements, please fo refer to:
-
This should work with python >= 3.6 but this is not guaranteed. ↩