Install & run backend¶

With docker¶

Requirements¶

Installation process¶

Docker will download backend image of Horizon & Postgres, and run them. Application settings are loaded from config.docker.yml. Settings omitted from the YAML file can be passed through the environment section in docker-compose.yml.

`docker-compose.yml`¶

services:
  db:
    image: postgres:17
    restart: unless-stopped
    environment:
      POSTGRES_DB: horizon
      POSTGRES_USER: horizon
      POSTGRES_PASSWORD: 123UsedForTestOnly
      POSTGRES_INITDB_ARGS: --encoding=UTF-8 --lc-collate=C --lc-ctype=C
    ports:
      - 5432:5432
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: [CMD-SHELL, 'pg_isready -d $${POSTGRES_DB} -U $${POSTGRES_USER}']
      start_period: 5s
      interval: 30s
      timeout: 5s
      retries: 3

  backend:
    image: mtsrus/horizon-backend:${VERSION:-latest}
    restart: unless-stopped
    environment:
      # PROMETHEUS_MULTIPROC_DIR is required for multiple workers, see:
      # https://prometheus.github.io/client_python/multiprocess/
      PROMETHEUS_MULTIPROC_DIR: /tmp/prometheus-metrics
    # tmpfs dir is cleaned up each container restart
    tmpfs:
      - /tmp/prometheus-metrics:mode=1777
    volumes:
      - ./config.docker.yml:/app/config.yml:ro
    ports:
      - 8000:8000
    depends_on:
      db:
        condition: service_healthy

volumes:
  postgres_data:

`config.docker.yml`¶

database:
  url: postgresql+asyncpg://horizon:123UsedForTestOnly@db:5432/horizon

auth:
  provider: horizon.backend.providers.auth.dummy.DummyAuthProvider
  access_token:
    secret_key: 234UsedForTestOnly
  ldap:
    url: ldap://ldap:389
    base_dn: ou=people,dc=ldapmock,dc=local
    lookup:
      credentials:
        user: uid=adminuser1,ou=people,dc=ldapmock,dc=local
        password: password

server:
  debug: true
  cors:
    enabled: true
    allow_origins: [http://localhost:3000]
    allow_credentials: true
    allow_methods: ['*']
    allow_headers: ['*']
    expose_headers: [X-Request-ID, Location, Access-Control-Allow-Credentials]

After container is started and ready, open http://localhost:8000/docs.

Users listed in the admin_users configuration field are automatically promoted to the SUPERADMIN role.

Without docker¶

Requirements without docker¶

Python 3.10 or above
Pydantic 2.x
libldap2-dev, libsasl2-dev, libkrb5-dev (for LDAP Auth provider)
Some relation database instance, like Postgres

Installation process without docker¶

Install data-horizon package with following extra dependencies:

$ pip install data-horizon[backend,postgres,ldap]
...

Available extras are:

backend - main backend requirements, like FastAPI, SQLAlchemy and so on.
postgres - requirements required to use Postgres as backend data storage.
ldap - requirements used by LDAP Auth provider.

Note

For macOS users, an additional step is required. You need to install the “bonsai” Python library from source code. This installation is necessary to work with LDAP.

Run database¶

Start Postgres instance somewhere, and set up the database URL in config.yml:

database:
  url: postgresql+asyncpg://user:password@postgres-host:5432/database_name

You can use virtually any database supported by SQLAlchemy, but the only one we really tested is Postgres.

If the value is omitted from config.yml, it can be passed using an environment variable:

export HORIZON__DATABASE__URL=postgresql+asyncpg://user:password@postgres-host:5432/database_name

See Database settings for more options.

Run migrations¶

To apply migrations (database structure changes) you need to execute following command:

$ python -m horizon.backend.db.migrations upgrade head
...

This is a thin wrapper around alembic cli, options and commands are just the same.

run migrations

This command should be executed after each upgrade to new Horizon version.

Run backend¶

To start backend server you need to execute following command:

$ python -m horizon.backend --host 0.0.0.0 --port 8000
...

This is a thin wrapper around uvicorn cli, options and commands are just the same.

After server is started and ready, open http://localhost:8000/docs.

Add admin users¶

List users which should automatically receive the SUPERADMIN role in config.yml:

admin_users:
  - admin1
  - admin2

Then run the following script without arguments, or pass usernames explicitly:

$ python -m horizon.backend.scripts.manage_admins add
$ python -m horizon.backend.scripts.manage_admins add admin1 admin2
...

See Scripts documentation.