Aleph requires a couple of services in order to operate. To make it easier for development and deployments it uses Docker containers. Below you will find the installation steps on how to install Aleph locally for development and production environment.


Before we continue, you will need to have Docker and docker-compose installed. Please refer to their manual to learn how to set up Docker and docker-compose.

You will also need to edit a configuration file to provide some credentials for the external services. This includes the OAuth credentials to allow Google users to login to Aleph and an email server credentials. Email server support is optional for development purposes.

Inside the same repository you will find a file called aleph.env.tmpl. This is a template of the configuration file. Make a copy of this file named aleph.env and follow the steps below to edit it.

To get the OAuth credentials please visit the Google Developers Console. There you will need to create an API key. In the Authorized redirect URIs section, use this URL:


Save the client ID and the client secret as ALEPH_OAUTH_* values.

Finally you will need to provide a value for the ALEPH_SECRET_KEY. A good example of a value is the output of openssl rand -hex 24.

Development installation steps

Insider the Aleph repository you will find a Dockerfile and a files. These are used to build a container with the application and start the relevant services.

To proceed run:

  1. make build to start the application and relevant services. You can leave this open to have access to the development logs.
  2. make upgrade to run the latest database migrations and create/update any indexes.
  3. make web to run the web-based API server.
  4. Open http://localhost:5000/ in your browser to visit the API server.

Your repository is mounted inside the docker container under the name aleph_app. You can access these services anytime by running make shell.

Building from a clean state

You can also build the Aleph images locally. This could be useful while working on the Dockerfile changes and new dependency upgrades.

Aleph provides two commands to build the images. First one is make base, this will build the alephdata/base image (this is an intermediary image with system-level dependencies for Aleph). The second one is make build, this will build the alephdata/aleph image (this will generate a production ready image).