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.
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
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.
Save the client ID and the client secret as
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
Docker and a
docker-compose.yml files. These are used to build a container with the
application and start the relevant services.
To proceed run:
docker-compose upto start the application and relevant services. You can leave this open to have access to the development logs.
docker-compose run app python aleph/manage.py init -s analyzersto run the latest database migrations and create/update any indexes.
http://lvh.me:13376/in your browser and proceed with the login.
Your repository is mounted inside the docker container under the name
aleph_app_1. You should also see the other Aleph services,
aleph_beat_1. You can access these services anytime by running
docker-compose run <app|worker|beat> bash.
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
alephdata/aleph image (this will generate a production ready image).
Aleph is transitioning the front-end codebase towards a more modern architecture and while this is still a work-in-progress, some of the features already landed and should make the front-end development easier.
An LTS version of Node.js with NPM is required before we continue.
First you will need to install the development packages (at the moment the
build tool uses Webpack 2):
npm install ..
If you are using Docker, none of this is required.
In order to build the front-end you will need to run:
The front-end assets are always built when you start the application.
If you are working on the front-end, you will need to start the assets watcher in parallel:
docker-compose run app make assets-dev
While working on the front-end development, make sure you disable browser cache!
Aleph runs on PostgreSQL and ElasticSearch along with a couple of system
tools like OpenOffice, ImageMagik, Tesseract and wkhtmltopdf. For a full list
of system dependencies please review the
If you decide to not use Docker compose, you will have to provide all these
dependencies and services and change the configuration file accordingly.
An application only Docker image is also available at
Finally, aleph is optimized to use certain Amazon Web Services: SQS and S3. To enable AWS features, you will need to set the AWS key ID and access key in the configuration file. Amazon SQS support is available for task queueing. Where S3 is available for file uploads.
Aleph does not provide automatic upgrades. You will have to download the new version Docker images or checkout the latest version using Git first.
Once you have the latest version, you can run the command bellow to upgrade the existing installation.
$ docker-compose run app aleph upgrade
Most of the Aleph configuration is handled via a set of values in a Python
configuration file. The defaults are documented in the
file and can be overridden by pointing to a bespoke configuration file using
the environment variable
While using Docker, the config file, in turn, is largely configured using environment variables in accordance with 12 factor principles. These environment variables can be found also in docker_settings.py.
TIKA_URI- when enabled, this will use Apache Tika to extract content from PDF files, rather than the built-in
tesseractmodules. The URI must point to a Tika server endpoint, which is also responsible for handling OCR.
Note: using Tika with OCR’d documents may yield different results from the built-in mechanism and OCR may not be performed on the same sections of a document’s content (See: #104).
To run the tests, assuming you already have the
docker-compose up and ready,
docker-compose run app make test.
This will create a new database and run all the tests.
The test settings can also be configured by making a copy of the
test_settings.py.tmpl file to
test_settings.py and editing it to
match your configuration. You must then set the environment
ALEPH_TEST_SETTINGS to point to the absolute path of that