Configuration Options

Aleph can be configured using environment variables to adjust it to your needs. This page lists all available configuration options.

General

ALEPH_SECRET_KEY

This key is used to sign and encrypt data, for example JWTs. Provide a long, unique value. A good way to generate a key is openssl rand -hex 24.

ALEPH_FORCE_HTTPS

Redirects all HTTP requests to HTTPS. Automatically enabled if ALEPH_UI_URL starts with https.

Default: false

ALEPH_URL_SCHEME

URL scheme used when generating URLs. Automatically set to https if ALEPH_UI_URL starts with https.

Default: https

ALEPH_CORS_ORIGINS

List of allowed HTTP CORS origins. Spearate multiple values using a pipe character |.

Default: *

ALEPH_API_RATE_LIMIT

Maximum number of API requests per minute. Applies to unauthenticated users only.

Default: 30

ALEPH_API_RATE_WINDOW

Window for rate limiting in minutes.

Default: 15

ALEPH_PROFILE

Enable request profiling.

Default: false

ALEPH_CACHE

Enable HTTP cache headers. Disabled in debug mode.

Default: true

ALEPH_MAINTENANCE

Enables read-only mode and displays a warning message.

Default: false

LOG_FORMAT

Render logs as unstructured text or in JSON format. Values are TEXT or JSON.

Default: TEXT

EXPORT_MAX_SIZE

File size limit for exports in bytes.

Default: 1073741824

EXPORT_MAX_RESULTS

Maximum number of results per export.

Default: 100000

ALEPH_PAGES_PATH

Path to a directory with markdown files used for the pages feature.

Default: /aleph/pages

ALEPH_ROLE_INACTIVE

Users who haven’t logged in for more than X days are considered inactive and won’t receive notification emails.

Default: 180

ALEPH_NOTIFICATIONS_DELETE

Notifications older than X days are deleted.

Default: 90

FTM_COMPARE_FREQUENCIES_DIR

Path to a directory with pickled word frequency objects used for cross-referencing.

Default: /opt/ftm-compare/word-frequencies/

FTM_COMPARE_MODEL

Path to the model used for cross-referencing.

Default: /opt/ftm-compare/model.pkl

ALEPH_MAX_EXPAND_ENTITIES

Maximum number of entities to return per property when expanding entities.

Default: 200

ALEPH_RESULT_HIGHLIGHT

Enable highlights in search result snippets.

Default: true

ALEPH_XREF_SCROLL

Scroll timeout used for Elasticsearch requests during cross-referencing.

Default: 5m

ALEPH_XREF_SCROLL_SIZE

Scroll size used for Elasticsearch requests during cross-referencing.

Default: 1000

User Interface

ALEPH_UI_URL

URL where the UI will be made available.

Default: http://localhost:8080

ALEPH_APP_TITLE

Title of the instance displayed in the UI.

Default: Aleph

ALEPH_LOGO

URL to logo displayed in the UI.

Default: /static/logo.png

ALEPH_FAVICON

URL to favicon.

Default: /static/favicon.png

ALEPH_UI_LANGUAGES

List of enabled languages. Users can select their preferred language. Separate multiple values using a colon :.

Default: ru:es:de:en:ar:fr

ALEPH_DEFAULT_LANGUAGE

Default UI language

Default: en

ALEPH_FEEDBACK_URL_DOCUMENTS

External link that allows users to report problems with ingested documents. You can use {{role_email}} and {{entity_url}} placeholders which will be replaced dynamically.

ALEPH_FEEDBACK_URL_TIMELINES

External link that allows useres to give feedback about the timelines feature in Aleph investigations.

ALEPH_APP_BANNER

Display a static message at the top of the screen. Refer to How to display a message banner for details.

ALEPH_APP_MESSAGES_URL

Load messages from this URL and display the most recent message at the top of the screen. Refer to How to display a message banner for details.

Ingestors

ALEPH_INGEST_PIPELINE

List of enabled stages. Separate multiple values using a colon :.

Default: analyze

INGESTORS_CONVERT_TIMEOUT

Timeout in hours for document conversions.

Default: 7200

INGESTORS_OCR_VISION_API

Use the Google Vision API instead of performing OCR locally using Tesseract.

Default: false

INGESTORS_LID_MODEL_PATH

Path to a fastText model used for language identification.

Default: /ingestors/data/lid.176.ftz

INGESTORS_TYPE_MODEL_PATH

???

Default: /models/model_type_prediction.ftz

INGESTORS_ANALYZE_ENTITIES

Enable analysis of entities.

Default: true

Databases and services

Refer to the architecture for details about how Aleph uses the different databases.

ALEPH_DATABASE_URI

Connection URI to a PostgreSQL database. This database is used to store non-entity data like collection metadata, users etc.

Default: postgresql://aleph:aleph@postgres/aleph

FTM_STORE_URI

Connection URI to a for PostgreSQL database. This database is used to store entity fragments.

Default: postgresql://aleph:aleph@postgres/aleph

ALEPH_ELASTICSEARCH_URI

ElasticSearch API endpoint

Default: http://elasticsearch:9200

ELASTICSEARCH_TIMEOUT

Timeout for ElasticSearch requests in seconds.

Default: 60

ALEPH_INDEX_REPLICAS

Number of index replicas. For example, 2 means that three copies of the data are maintained (primary shard + 2 replicas).

Default: 0

ALEPH_INDEX_PREFIX

Index prefix used in ElasticSearch queries.

Default: aleph

ALEPH_INDEX_WRITE

Index suffixes used for ElasticSearch write queries.

Default: v1

ALEPH_INDEX_READ

List of index suffixes used for ElasticSearch read queries. Separate multiple values using a colon :.

Default: v1

ALEPH_INDEX_EXPAND_CLAUSE_LIMIT

???

Default: 10

ALEPH_INDEX_DELETE_BY_QUERY_BATCHSIZE

???

Default: 100

REDIS_URL

Connection URI to a Redis database.

Default: redis://redis:6379/0

REDIS_EXPIRE

Default expiration timeout for redis keys in seconds.

Default: 592900

Workers

WORKER_RETRY

Default number of times failed tasks are retried.

Default: 3

WORKER_THREADS

Number of threads per worker.

Default: Number of CPU

WORKER_REPORTING

???

Default: true

Storage

By default, Aleph stores uploaded files on the local file system. You can configure Aleph to use an external blob storage service like AWS S3 or Google Cloud Storage instead. Depending on the service, you may need to set additional configuration options (see Cloud providers).

ARCHIVE_TYPE

Storage backend to use for uploads. Values are s3 (AWS S3), gs (Google Cloud Storage), or file (local file system).

Default: file

ARCHIVE_PATH

Path to directory when using the local file system.

Default: /data

ARCHIVE_BUCKET

Bucket name used for uploads when using AWS S3 or Google Cloud Storage.

PUBLICATION_BUCKET

Bucket name used to make files publicly available when using AWS S3 or Google Cloud Storage.

Cloud providers

Aleph currently supports AWS S3 (and S3-compatible services) for file storage and the Google Cloud Vision API for OCR. If you want to use one of these services, make sure to set the respective configuration options.

ARCHIVE_ENDPOINT_URL

AWS service endpoint URL.

AWS_ACCESS_KEY_ID

AWS access key ID.

AWS_SECRET_ACCESS_KEY

AWS secret access key.

AWS_REGION

AWS region.

Default: eu-west-1

GOOGLE_APPLICATION_CREDENTIALS

Path to a Google Cloud service account JSON keyfile.

Authentication

ALEPH_ADMINS

List of email addresses. Users with one of these email addresses will have admin permissions.

ALEPH_SYSTEM_USER

ID of the default system user.

Default: system:aleph

ALEPH_REQUIRE_LOGGED_IN

Require authentication in order to browser Aleph.

Default: false

ALEPH_PASSWORD_LOGIN

Enable password authentication. Disabled when OAuth is configured.

Default: true

ALEPH_SESSION_EXPIRE

Session expiration in seconds.

Default: 60000

ALEPH_ROLE_BLOCKED_MESSAGE

Message that is displayed when a blocked user tries to log in.

Default: Your account has been blocked.

ALEPH_ROLE_BLOCKED_LINK

Target of the link displayed below the message that is displayed when a blocked user tries to log in. You can use this to link further information on what users can do if their account has been blocked etc.

Default: None

ALEPH_ROLE_BLOCKED_LINK_LABEL

Label of the link that is displayed when a blocked user tries to log in.

Default: None

OAuth

Use these configuration options to configure an external OAuth provider. Some of these options may be optional depending on your provider. Refer to “How configure an OAuth provider” for details.

ALEPH_OAUTH

Default: false

ALEPH_OAUTH_MIGRATE_SUB

Default: false

ALEPH_OAUTH_HANDLER

Default: oidc

ALEPH_OAUTH_KEY

ALEPH_OAUTH_SECRET

ALEPH_OAUTH_SCOPE

Default: openid email provider

ALEPH_OAUTH_AUDIENCE

ALEPH_OAUTH_METADATA_URL

ALEPH_OAUTH_TOKEN_METHOD

Default: POST

ALEPH_OAUTH_ADMIN_GROUP

Default: superuser

Email

Aleph sends notification and authentication emails. The following options are used to configure outbound email. They map to the configuration options exposed by Flask-Mail.

ALEPH_MAIL_FROM

Default: aleph@domain.com

ALEPH_MAIL_HOST

Default: localhost

ALEPH_MAIL_USERNAME

ALEPH_MAIL_PASSWORD

ALEPH_MAIL_SSL

Default: false

ALEPH_MAIL_TLS

Default: true

ALEPH_MAIL_PORT

Default: 465

ALEPH_MAIL_DEBUG

Default: false

Monitoring

SENTRY_DSN

Sentry DSN. Refer to the Sentry documentation for details.

SENTRY_ENVIRONMENT

Sentry environment. Refer to the Sentry documentation for details.

SENTRY_CAPTURE_PROCESSING_EXCEPTIONS

Report exceptions that occur during processing of uploaded files to Sentry. Enable this with care as it can easily eat up the Sentry event quota if you upload a lot of files.

Default: false

PROMETHEUS_ENABLED

Enable Prometheus metrics. Refer to How to set up Prometheus metrics for details.

Default: false

PROMETHEUS_PORT

Port for Prometheus metrics endpoint

Default: 9100

Feature flags

ALEPH_ENABLE_EXPERIMENTAL_BOOKMARKS_FEATURE

Enable experimental bookmarks feature. Bookmarks are stored client-side and users may accidentally delete them when clearing browser data.

Default: false

Development

ALEPH_DEBUG

Enable the Flask debug mode.

Default: false

ALEPH_SINGLE_USER

Disables authentication and authorization and automatically logs anyone in with admin permissions.

Default: false

Additional configuration options

Aleph’s backend is a Flask application. You can set arbitrary configuration options of the Flask app configuration object using environment variables. This is helpful in case you need to directly adjust a configuration option exposed by Flask or another package and Aleph doesn’t provide a respective configuration option.

In order to enable this feature, set ALEPH_STRING_CONFIG_PREFIX. Aleph will then load all environment variables starting with the configured prefix and append them to the Flask app configuration. In the following example, the Flask MAX_CONTENT_LENGTH configuration options will be set.

ALEPH_STRING_CONFIG_PREFIX=CUSTOM_
CUSTOM_MAX_CONTENT_LENGTH=1048576

Similarly, this also works for complex, non-string configuration options. Set ALEPH_JSON_CONFIG_PREFIX and Aleph will load all environment variables starting with the configured prefix, trying to parse values as JSON.