Storage Backends

This section details how to declare and use storage backends for artifacts produced by Horizon (magic link reports and archives).

Horizon supports two storage backend types:

  • local: MongoDB GridFS, stored in Horizon’s primary database. A single local backend exists implicitly and does not require any UI configuration.

  • s3: an Amazon S3 bucket or any S3-compatible object storage. Any number of s3 backends can be declared.

The backend types that can actually be created are constrained by the optional horizon.storage.whitelist HOCON key:

  • if the key is absent or set to an empty list, all backend types are authorized;

  • if the key is set, only the listed types are available through the API. For example, horizon.storage.whitelist = ["s3"] prevents creating or using the implicit local backend.

Whitelisting applies to both static and dynamic backends. Non-whitelisted entries are filtered out of list and get operations.

How to configure a Storage Backend

1. Log in to Horizon Administration Interface.

2. Access Storages from the drawer or card: Configuration  System  Storages.

3. Click on Add storage.

4. Fill in the mandatory fields.

  • Name* (string input):
    Enter a meaningful name for the storage backend. It must be unique across all storage backends.

  • Type* (select):
    Only s3 is creatable. The local backend is implicit and cannot be created from the UI.

  • Endpoint* (string input):
    URL of the S3 endpoint (e.g. https://s3.eu-west-3.amazonaws.com or the URL of a self-hosted S3-compatible service).

  • Region* (string input):
    S3 region the bucket belongs to.

  • Bucket* (string input):
    Name of the bucket where artifacts are written.

  • Path style access (boolean):
    Use path-style URLs (https://<endpoint>/<bucket>/<key>;) instead of virtual-hosted style. Required for most S3-compatible services. The default value is set to false.

  • Credentials* (select):
    Select an API Token credentials entry holding the S3 access key and secret key. Credentials must declare storage as their target.

  • Proxy (string select):
    HTTP/HTTPS proxy used to reach the S3 endpoint, if any.

5. Click on the save button.

You can update Edit storage or delete Delete storage a Storage Backend.

A storage backend cannot be deleted while it is referenced in the system storage configuration (see below).

How to assign Storage Backends to artifacts

Once a storage backend is declared, it must be selected as the destination for each artifact type. This is done from the System storage configuration drawer (expert mode only):

  • Archive storage (string select):
    Storage backend used to write archives. If left empty, archives are written to the implicit local backend (only allowed if local is whitelisted).

  • Magic link report storage (string select):
    Storage backend used to write magic link reports. If left empty, reports are written to the implicit local backend (only allowed if local is whitelisted).

Changing the destination only affects newly produced artifacts. Existing artifacts remain on the backend they were originally written to. Refer to the archives page for the impact on archive deletion when using a non-local backend.