Installation
If you would like to contribute to Dallinger, please follow these alternative install instructions.
Installation Options
Dallinger is tested on recent Ubuntu-based Linux distributions and on MacOS locally. We do not recommend running Dallinger with Microsoft Windows, however if you do, running Ubuntu in a virtual machine is the recommended method.
Using Dallinger with Docker
Docker is a containerization tool used for developing isolated software environments. Read more about using Dallinger with Docker here.
Installing Docker
To install Docker on Linux, run this command:
curl https://get.docker.com | sudo sh
On MacOS you can download Docker Desktop from the official Docker website: https://docs.docker.com/desktop/mac/install/
Using docker to run postgres and redis
Dallinger can start a postgres database and a redis server for you. To do this, run the following command:
dallinger docker start-services
To free up resources you can stop the services when they’re not needed anymore:
dallinger docker stop-services
MacOS
Install Python
Dallinger is written in Python. To determine the exact supported Python versions, please refer to the pyproject.toml on GitHub file.
You can check your installed version with:
python3 --version
Note
You will also need to have pip installed. It is included in some of the later versions of Python 3, but not all. (pip is a package manager for Python packages, or modules if you like.) If you are using Python 3, you may find that you may need to use the pip3 command instead of pip where applicable in the instructions that follow.
Important
We do not recommend installing Python via Homebrew, since Homebrew updates will replace Python versions and can break virtual environments.
Instead, we recommend one of the following approaches:
Official Python Installer (simplest): Download and install Python directly from the Python.org downloads page. This will give you a stable installation suitable for creating virtual environments.
pyenv (optional, for managing multiple Python versions): If you need to switch between different Python versions across projects, you may want to use pyenv. pyenv lets you install and select different Python versions independently of the system Python. On macOS it can be installed via Homebrew:
brew install pyenv pyenv install 3.12 pyenv local 3.12
For setup instructions, follow the pyenv installation guide.
Both approaches will give you a working Python 3 interpreter. Once installed, you should have access to both python3 and pip3 from the terminal.
Should that not work for whatever reason, you can search here for more clues.
Install Postgresql
The easiest way to install Postgresql is to use docker.
On MacOS, we recommend installing using Homebrew:
brew install postgresql@12
brew link postgresql@12
Postgresql can then be started and stopped using:
brew services start postgresql@12
brew services stop postgresql@12
Create the databases
After installing Postgres, you will need to create two databases: one for your experiments to use, and a second to support importing saved experiments. It is recommended that you also create a database user.
Navigate to a terminal and type:
createuser -P dallinger --createdb
(Password: dallinger)
createdb -O dallinger dallinger
createdb -O dallinger dallinger-import
The first command will create a user named dallinger and prompt you for a
password. The second and third command will create the dallinger and
dallinger-import databases, setting the newly created user as the owner.
You can optionally inspect your databases by entering psql dallinger.
Inside psql you can use commands to see the roles and database tables:
\du
\l
To quit:
\q
If you get an error like the following:
createuser: could not connect to database postgres: could not connect to server:
Is the server running locally and accepting
connections on Unix domain socket "/tmp/.s.PGSQL.5432"?
then postgres is not running. Start postgres as described in the Install Postgresql section above.
Install Heroku
To run experiments locally or on the internet, you will need the Heroku Command Line Interface installed, version 3.28.0 or better. If you want to launch experiments on the internet, then you will also need a Heroku.com account, however this is not needed for local debugging.
To check which version of the Heroku CLI you have installed, run:
heroku --version
To install:
brew install heroku/brew/heroku
More information on the Heroku CLI is available at heroku.com along with alternative installation instructions, if needed.
Install Redis
The easiest way to install Redis is to use docker.
Debugging experiments requires you to have Redis installed and the Redis server running.
brew install redis
Start Redis on MacOS with:
brew services start redis
You can find more details and other installation instructions at redis.com.
Install Git
Dallinger uses Git, a distributed version control system, for version control of its code. If you do not have it installed, you can install it as follows:
brew install git
You will need to configure your Git name and email:
git config --global user.email "you@example.com"
git config --global user.name "Your Name"
Replace you@example.com and Your Name with your email and name to set your account’s default identity.
Omit –global to set the identity only in this repository. You can read more about configuring Git here.
Install Dallinger
Navigate to the directory where you want to house your development work on Dallinger. Once there, clone the Git repository using:
git clone https://github.com/Dallinger/Dallinger
This will create a directory called Dallinger in your current
directory.
Change into your new directory with:
cd Dallinger
Set up a virtual environment
Why use virtualenv?
Virtualenv solves a very specific problem: it allows multiple Python projects that have different (and often conflicting) requirements, to coexist on the same computer. If you want to understand this in detail, you can read more about it here.
We recommend using Python’s built-in venv module to create a virtual environment:
Note
These instructions assume you’re using the bash shell. If you’re using zsh or another shell, adjust paths accordingly.
python3 -m venv .venv
source .venv/bin/activate
To deactivate the virtual environment later, run:
deactivate
Alternative: Using virtualenvwrapper
If you’re already familiar with virtualenv and virtualenvwrapper, you can still use them. Here’s an example using mkvirtualenv:
pip3 install virtualenv
pip3 install virtualenvwrapper
export WORKON_HOME=$HOME/.virtualenvs
mkdir -p $WORKON_HOME
export VIRTUALENVWRAPPER_PYTHON=$(which python3.12)
source $(which virtualenvwrapper.sh)
Now create the virtual environment using:
mkvirtualenv dlgr_env --python <specify_your_python_path_here>
Example:
mkvirtualenv dlgr_env --python /usr/local/bin/python3.12
Virtualenvwrapper provides an easy way to switch between virtual environments
by simply typing: workon [virtual environment name].
The technical details:
These commands use pip/pip3, the Python package manager, to install two
packages virtualenv and virtualenvwrapper. They set up an
environmental variable named WORKON_HOME with a string that gives a
path to a subfolder of your home directory (~) called Envs,
which the next command (mkdir) then makes according to the path
described in $WORKON_HOME (recursively, due to the -p flag).
That is where your environments will be stored. The source command
will run the command that follows, which in this case locates the
virtualenvwrapper.sh shell script, the contents of which are beyond
the scope of this setup tutorial. If you want to know what it does, a
more in depth description can be found on the documentation site for virtualenvwrapper.
Finally, the mkvirtualenv makes your first virtual environment which
you’ve named dlgr_env. We have explicitly passed it the location of the Python
that the virtualenv should use. This Python has been mapped to the python
command inside the virtual environment.
The how-to:
In the future, you can work on your virtual environment by running:
export VIRTUALENVWRAPPER_PYTHON=$(which python3.12)
source $(which virtualenvwrapper.sh)
workon dlgr_env
NB: To stop working in the virtual environment, run deactivate. To
list all available virtual environments, run workon with no
arguments.
If you plan to do a lot of work with Dallinger, you can make your shell
execute the virtualenvwrapper.sh script everytime you open a terminal. To
do that type:
echo "export VIRTUALENVWRAPPER_PYTHON=$(which python3.12)" >> ~/.bash_profile
echo "source $(which virtualenvwrapper.sh)" >> ~/.bash_profile
From then on, you only need to use the workon command before starting.
Remove a Virtual Environment
If you no longer need the virtual environment, you can safely delete it.
If you used Python’s built-in venv:
deactivate # If it's still active
rm -rf .venv
This will remove the entire virtual environment folder. You can recreate it later if needed.
If you used virtualenvwrapper:
deactivate # If it's still active
rmvirtualenv dlgr_env
This will delete the dlgr_env environment from the WORKON_HOME directory.
Note
The rmvirtualenv command is only available when virtualenvwrapper.sh has been sourced.
If it’s unavailable, you can manually delete the folder inside $WORKON_HOME.
Install Python dependencies
Now we need to install the dependencies using pip:
pip install dallinger[data]
Test that your installation works by running:
dallinger --version
Next, you’ll need access keys for AWS, Heroku, etc..
Ubuntu
Install Python
Dallinger is written in Python. To determine the exact supported Python versions, please refer to the pyproject.toml on GitHub file.
You can check your installed version with:
python3 --version
Note
You will also need to have pip installed. It is included in some of the later versions of Python 3, but not all. (pip is a package manager for Python packages, or modules if you like.) If you are using Python 3, you may find that you may need to use the pip3 command instead of pip where applicable in the instructions that follow.
Important
We do not recommend using the system Python provided by Ubuntu for development if you plan to manage multiple projects or upgrade your OS regularly. The system Python is tied to Ubuntu and can cause conflicts with packages or break virtual environments after upgrades.
Instead, use one of the following approaches:
Official Python Installer (simplest): Download and install Python directly from the Python.org downloads page. This gives you a stable installation independent from the system Python.
pyenv (optional, for managing multiple Python versions): If you often need to switch between different Python versions across projects, you may want to use pyenv. pyenv lets you install and select different Python versions independently of the system Python.
curl -fsSL https://pyenv.run | bash pyenv install 3.12 pyenv local 3.12
For setup instructions, follow the pyenv installation guide.
Ubuntu packages (not recommended): If you prefer to use Ubuntu packages, you can install Python 3 and headers with:
sudo apt-get install -y python3 python3-dev python3-pip
This works, but be aware that system updates may change the available Python versions and affect your environments.
Once installed, you should have access to both python3 and pip3 from the terminal.
Should that not work for whatever reason, you can search here for more clues.
Install Postgresql
The lowest version of Postgresql that Dallinger v5 supports is 9.4.
Postgres can be installed using the following instructions:
sudo apt-get update && sudo apt-get install -y postgresql postgresql-contrib libpq-dev
To run postgres, use the following command:
sudo service postgresql start
Create the databases
Make sure that postgres is running. Switch to the postgres user:
sudo -u postgres -i
Run the following commands:
createuser -P dallinger --createdb
(Password: dallinger)
createdb -O dallinger dallinger
createdb -O dallinger dallinger-import
exit
The second command will create a user named dallinger and prompt you for a
password. The third and fourth commands will create the dallinger and dallinger-import databases, setting
the newly created user as the owner.
Finally restart postgresql:
sudo service postgresql reload
Install Heroku
To run experiments locally or on the internet, you will need the Heroku Command Line Interface installed, version 3.28.0 or better. If you want to launch experiments on the internet, then you will also need a Heroku.com account, however this is not needed for local debugging.
To check which version of the Heroku CLI you have installed, run:
heroku --version
To install:
sudo apt-get install curl
curl https://cli-assets.heroku.com/install.sh | sh
More information on the Heroku CLI is available at heroku.com along with alternative installation instructions, if needed.
Install Redis
Debugging experiments requires you to have Redis installed and the Redis server running.
sudo apt-get install -y redis-server
Start Redis on Ubuntu with:
sudo service redis-server start
You can find more details and other installation instructions at redis.com.
Install Git
Dallinger uses Git, a distributed version control system, for version control of its code. If you do not have it installed, you can install it as follows:
sudo apt install git
You will need to configure your Git name and email:
git config --global user.email "you@example.com"
git config --global user.name "Your Name"
Replace you@example.com and Your Name with your email and name to set your account’s default identity.
Omit –global to set the identity only in this repository. You can read more about configuring Git here.
Install Dallinger
Navigate to the directory where you want to house your development work on Dallinger. Once there, clone the Git repository using:
git clone https://github.com/Dallinger/Dallinger
This will create a directory called Dallinger in your current
directory.
Change into your new directory with:
cd Dallinger
Set up a virtual environment
Why use virtualenv?
Virtualenv solves a very specific problem: it allows multiple Python projects that have different (and often conflicting) requirements, to coexist on the same computer. If you want to understand this in detail, you can read more about it here.
We recommend using Python’s built-in venv module to create a virtual environment:
Note
These instructions assume you’re using the bash shell. If you’re using zsh or another shell, adjust paths accordingly.
python3 -m venv .venv
source .venv/bin/activate
To deactivate the virtual environment later, run:
deactivate
Alternative: Using virtualenvwrapper
If you’re already familiar with virtualenv and virtualenvwrapper, you can still use them. Here’s an example using mkvirtualenv:
pip3 install virtualenv
pip3 install virtualenvwrapper
export WORKON_HOME=$HOME/.virtualenvs
mkdir -p $WORKON_HOME
export VIRTUALENVWRAPPER_PYTHON=$(which python3.12)
source $(which virtualenvwrapper.sh)
Now create the virtual environment using:
mkvirtualenv dlgr_env --python <specify_your_python_path_here>
Example:
mkvirtualenv dlgr_env --python /usr/local/bin/python3.12
Virtualenvwrapper provides an easy way to switch between virtual environments
by simply typing: workon [virtual environment name].
The technical details:
These commands use pip/pip3, the Python package manager, to install two
packages virtualenv and virtualenvwrapper. They set up an
environmental variable named WORKON_HOME with a string that gives a
path to a subfolder of your home directory (~) called Envs,
which the next command (mkdir) then makes according to the path
described in $WORKON_HOME (recursively, due to the -p flag).
That is where your environments will be stored. The source command
will run the command that follows, which in this case locates the
virtualenvwrapper.sh shell script, the contents of which are beyond
the scope of this setup tutorial. If you want to know what it does, a
more in depth description can be found on the documentation site for virtualenvwrapper.
Finally, the mkvirtualenv makes your first virtual environment which
you’ve named dlgr_env. We have explicitly passed it the location of the Python
that the virtualenv should use. This Python has been mapped to the python
command inside the virtual environment.
The how-to:
In the future, you can work on your virtual environment by running:
export VIRTUALENVWRAPPER_PYTHON=$(which python3.12)
source $(which virtualenvwrapper.sh)
workon dlgr_env
NB: To stop working in the virtual environment, run deactivate. To
list all available virtual environments, run workon with no
arguments.
If you plan to do a lot of work with Dallinger, you can make your shell
execute the virtualenvwrapper.sh script everytime you open a terminal. To
do that type:
echo "export VIRTUALENVWRAPPER_PYTHON=$(which python3.12)" >> ~/.bash_profile
echo "source $(which virtualenvwrapper.sh)" >> ~/.bash_profile
From then on, you only need to use the workon command before starting.
Remove a Virtual Environment
If you no longer need the virtual environment, you can safely delete it.
If you used Python’s built-in venv:
deactivate # If it's still active
rm -rf .venv
This will remove the entire virtual environment folder. You can recreate it later if needed.
If you used virtualenvwrapper:
deactivate # If it's still active
rmvirtualenv dlgr_env
This will delete the dlgr_env environment from the WORKON_HOME directory.
Note
The rmvirtualenv command is only available when virtualenvwrapper.sh has been sourced.
If it’s unavailable, you can manually delete the folder inside $WORKON_HOME.
Install Python dependencies
Now we need to install the dependencies using pip:
pip install dallinger[data]
Test that your installation works by running:
dallinger --version
Next, you’ll need access keys for AWS, Heroku, etc..