System-wide installation#
The system-wide installation will install the prerequisite services (PostgreSQL and RabbitMQ) via standard package managers such that their startup and shut-down is largely managed by the operating system. The AiiDA (core) Python package is then installed either with Conda or pip.
Warning
RabbitMQ v3.5 and below are EOL and not supported at all. For versions RabbitMQ v3.8.15 and up, AiiDA is not compatible with default server configurations. For details refer to the dedicated troubleshooting section.
This is the recommended installation method to setup AiiDA on a personal laptop or workstation for the majority of users.
AiiDA is designed to run on Unix operating systems and requires a bash or zsh shell, and Python >= 3.7.
AiiDA is tested on Ubuntu versions 16.04, 18.04, and 20.04.
Open a terminal and execute:
$ sudo apt install git python3-dev python3-pip postgresql postgresql-server-dev-all postgresql-client rabbitmq-server
The recommended installation method for Mac OS X is to use Homebrew.
Follow this guide to install Homebrew on your system if not installed yet.
Open a terminal and execute:
$ brew install postgresql rabbitmq git python $ brew services start postgresql $ brew services start rabbitmq
The following instructions are for setting up AiiDA on WSL 1/2 in combination with Ubuntu.
Installing RabbitMQ:
(WSL 1) Install and start the Windows native RabbitMQ.
(WSL 2) Install RabbitMQ inside the the WSL:
$ sudo apt install rabbitmq-server
then start the
rabbitmq
server:$ sudo service rabbitmq-server start
Install Python and PostgreSQL:
$ sudo apt install postgresql postgresql-server-dev-all postgresql-client git python3-dev python-pip
then start the PostgreSQL server:
$ sudo service postgresql start
How to setup WSL to automatically start services after system boot.
Create a file start_aiida_services.sh
containing the following lines:
$ service postgresql start
$ service rabbitmq-server start # Only for WSL 2!
and store it in your preferred location, e.g., the home directory. Then make the file executable, and editable only by root users with:
$ chmod a+x,go-w /path/to/start_aiida_services.sh
$ sudo chown root:root /path/to/start_aiida_services.sh
Next, run
$ sudo visudo
and add the line
<username> ALL=(root) NOPASSWD: /path/to/start_aiida_services.sh
replacing <username>
with your Ubuntu username.
This will allow you to run only this specific .sh
file with root
access (without password), without lowering security on the rest of your system.
Now you can use the Windows Task Scheduler to automatically execute this file on startup:
Open Task Scheduler.
In the “Actions” menu, click “Create Task”.
In “General/Security options”, select “Run whether user is logged on or not”.
In the “Triggers” tab, click “New…”.
In the “Begin the task:” dropdown, select “At startup”.
Click “OK” to confirm.
In the “Actions” tab, click “New…”.
In the “Action” dropdown, select “Start a program”.
In the “Program/script” text field, add
C:\Windows\System32\bash.exe
.In the “Add arguments (optional)” text field, add
-c "sudo /path/to/start_aiida_services.sh"
.Click “OK” to confirm.
Click “OK” to confirm the task.
You can tweak other details of this task to fit your needs.
Install RabbitMQ following the instructions applicable to your system.
Install PostgreSQL following the instructions applicable to your system.
Tip
Alternatively use the pure conda installation method.
Install the aiida-core package from PyPI into a virtual environment.
Open a terminal and execute:
$ python -m venv ~/envs/aiida
$ source ~/envs/aiida/bin/activate
(aiida) $ pip install aiida-core
Important
Make sure the python
executable is for a Python version that is supported by AiiDA.
You can see the version using:
$ python --version
You can find the supported Python versions for the latest version of AiiDA on the PyPI page.
Tip
See the venv documentation if the activation command fails. The exact command for activating a virtual environment differs slightly based on the used shell.
Installation extras
There are additional optional packages that you may want to install, which are grouped in the following categories:
atomic_tools
: packages that allow importing and manipulating crystal structure from various formatsssh_kerberos
: adds support for ssh transport authentication through KerberosREST
: allows a REST server to be ran locally to serve AiiDA datadocs
: tools to build the documentationnotebook
: jupyter notebook - to allow it to import AiiDA modulestests
: python modules required to run the automatic unit testspre-commit
: pre-commit tools required for developers to enable automatic code linting and formatting
In order to install any of these package groups, simply append them as a comma separated list in the pip
install command, for example:
(aiida) $ pip install aiida-core[atomic_tools,docs]
Kerberos on Ubuntu
If you are installing the optional ssh_kerberos
and you are on Ubuntu you might encounter an error related to the gss
package.
To fix this you need to install the libffi-dev
and libkrb5-dev
packages:
$ sudo apt-get install libffi-dev libkrb5-dev
Install the aiida-core package in a Conda environment.
Make sure that conda is installed, e.g., by following the instructions on installing Miniconda.
Open a terminal and execute:
$ conda create -yn aiida -c conda-forge aiida-core $ conda activate aiida
Install the aiida-core package directly from the cloned repository.
Open a terminal and execute:
$ git clone https://github.com/aiidateam/aiida-core.git
$ cd aiida-core/
$ python -m venv ~/envs/aiida
$ source ~/envs/aiida/bin/activate
(aiida) $ pip install .
Next, set up an AiiDA configuration profile and related data storage, with the verdi quicksetup
command.
(aiida) $ verdi quicksetup
Info: enter "?" for help
Info: enter "!" to ignore the default and set no value
Profile name: me
Email Address (for sharing data): me@user.com
First name: my
Last name: name
Institution: where-i-work
Start the verdi daemon(s) that are used to run AiiDA workflows.
(aiida) $ verdi daemon start 2
Important
The verdi daemon(s) must be restarted after a system reboot.
Tip
Do not start more daemons then there are physical processors on your system.
To check that everything is set up correctly, execute:
(aiida) $ verdi status
✓ version: AiiDA v2.0.0
✓ config: /path/to/.aiida
✓ profile: default
✓ storage: Storage for 'default' @ postgresql://username:***@localhost:5432/db_name / file:///path/to/repository
✓ rabbitmq: Connected as amqp://127.0.0.1?heartbeat=600
✓ daemon: Daemon is running as PID 2809 since 2019-03-15 16:27:52
At this point you should now have a working AiiDA environment, from which you can add and retrieve data.