Skip to main content

Declarative system configuration

What is it for?​

The backend API of docuteam Context offers functionality to declaratively set up archives and their included configurations using versioned YAML files.

The typical use cases are:

  • preparing and reviewing configuration changes before applying them,
  • keeping a readable history of configuration changes,
  • reusing the same setup in another environment,
  • restoring a known configuration state.

The API expects the client to have the role siteadmin.

What can you configure?​

The configuration currently covers these archive-level settings:

  • attachment connection settings,
  • app configuration,
  • box connections.

Structure of the configuration​

This is an example configuration which includes all currently available properties:

version: 1
archives:
  - name: myArchive
    attachment:
      connection:
        region: context
        endpoint: http://localhost:9000
        accessKey: admin
        secretKey: ENV(archive_myArchive_attachmentConnection_secretKey)
        bucketName: context-s3-mock
        downloadUrlMaxAgeInSeconds: 60
        maxFileSizeInBytes: 5368709120
        allowedMimeTypes:
          - application/pdf
          - image/jpeg
    appConfig:
      appTitle: Development server
      header:
        icon: <encoded_image>
        backgroundColor: "#FFFFFF"
        textColor: "#000000"
      menu:
        backgroundColor: "#FFFFFF"
        textColor: "#000000"
        textColorHover: "#222222"
    boxConnections:
      - name: public-box
        url: https://example.com/box
        namespace:
          - public
        token: ENV(archive_myArchive_boxConnection_public-box_token)

version denotes the current version of the implementation

archives is a list of the existing archives. The name property denotes the unique identifier of each archive. If you want absolutely no configuration state, you can leave the value of archives empty. The minimal valid configuration is therefore:

version: 1
archives:

connection defines a connection point for attachments. It can be left empty to not include a connection but if you want to configure it, you must include all of region, endpoint, accessKey, secretKey, bucketName, downloadUrlMaxAgeInSeconds, maxFileSizeInBytes, allowedMimeTypes.

appConfig configures the appearance of the application. All its properties are optional, so it can either be left fully empty or include only the desired ones.

boxConnections is a list of box connections. It can be left empty to not include any connections. If a connection is added it must include all of name, url, namespace and token.

The minimal configuration for a single archive is therefore:

version: 1
archives:
  - name: myArchive
    attachment:
      connection:
    appConfig:
    boxConnections:

Environment variables​

Secret properties can reference environment variables by using ENV(env_variable_key) as the value.

The intended naming of the keys for the attachment connection and box connections is: ENV(archive_$archiveName_attachmentConnection_secretKey) ENV(archive_$archiveName_boxConnection_$boxName_token)

This convention is used when fetching the current configuration state.

Fetching the current configuration​

Use the GET /api/system-config/get endpoint to export the current system configuration as YAML.

The response content type is application/yaml.

The endpoint returns the configuration serialized as YAML text, i.e. the response body is a YAML string rather than a JSON object.

Flags​

The endpoint supports the following optional query flag:

  • includeInfo=true
    Adds an info section at the top of the exported YAML. This section contains metadata about the export:
    • date: the timestamp of the export in ISO format,
    • user: the username of the authenticated user if available.

If the flag is omitted, or set to any value other than true, the info section is not included.

Examples​

Fetch the current configuration without metadata:

curl \
  -H "Accept: application/yaml" \
  -H "Authorization: Bearer <access-token>" \
  "http://localhost:3333/api/system-config/get"

Fetch the current configuration including export metadata:

curl \
  -H "Accept: application/yaml" \
  -H "Authorization: Bearer <access-token>" \
  "http://localhost:3333/api/system-config/get?includeInfo=true"

Example response with includeInfo=true:

version: 1
archives:
  - name: myArchive
    attachment:
      connection:
    appConfig:
    boxConnections:
info:
  date: 2026-06-10T12:00:00.000Z
  user: alice

The exported YAML can be reviewed, versioned and later submitted again to the apply endpoint. If an info section is present, it is ignored during import.

Applying a configuration​

Use the POST /api/system-config/apply endpoint to validate and apply a YAML configuration.

Send the YAML document itself as the raw request body with content type application/yaml.

The request body is parsed as plain text first and then interpreted as YAML. In other words, the endpoint expects a YAML string body.

Flags​

The endpoint supports the following optional query flag:

  • dryRun=true
    Validates the YAML, resolves environment-variable references, compares the desired state with the current state and returns the planned changes, but does not apply them.

If the flag is omitted, or set to any value other than true, the configuration is actually applied.

Examples​

Validate a configuration without applying it:

curl \
  -X POST \
  -H "Content-Type: application/yaml" \
  -H "Authorization: Bearer <access-token>" \
  --data-binary @system-config.yaml \
  "http://localhost:3333/api/system-config/apply?dryRun=true"

Apply a configuration:

curl \
  -X POST \
  -H "Content-Type: application/yaml" \
  -H "Authorization: Bearer <access-token>" \
  --data-binary @system-config.yaml \
  "http://localhost:3333/api/system-config/apply"

Response​

The endpoint returns a plain-text status report describing the result of the validation and apply process..

Typical responses are:

  • No changes
    The submitted configuration already matches the current system state.

  • A list of planned or executed changes, for example:

    update Archive myArchive
    - attachment.connection.endpoint: http://old.example -> http://new.example

  • If changes were actually applied successfully, the response ends with:

    Changes applied successfully.

Validation and environment variables​

During import, the YAML is parsed and validated strictly:

  • invalid YAML syntax,
  • missing required properties,
  • unknown properties,
  • duplicate archive names or duplicate box connection names within the same archive result in a 400 Bad Request.

Environment variable references in the form ENV(MY_KEY) are resolved during import. If a referenced environment variable is missing, the request fails.

An exported file with an info block can be sent back to the apply endpoint unchanged, because the info block is ignored during import.