docspell/modules/restserver/src/main/resources/reference.conf

docspell.server {

  # This is shown in the top right corner of the web application
  app-name = "Docspell"

  # This is the id of this node. If you run more than one server, you
  # have to make sure to provide unique ids per node.
  app-id = "rest1"

  # This is the base URL this application is deployed to. This is used
  # to create absolute URLs and to configure the cookie.
  #
  # If default is not changed, the HOST line of the login request is
  # used instead or the value of the `X-Forwarded-For` header. If set
  # to some other value, the request is not inspected.
  base-url = "http://localhost:7880"

  # Where the server binds to.
  bind {
    address = "localhost"
    port = 7880
  }

  # This is a hard limit to restrict the size of a batch that is
  # returned when searching for items. The user can set this limit
  # within the client config, but it is restricted by the server to
  # the number defined here. An admin might choose a lower number
  # depending on the available resources.
  max-item-page-size = 200

  # The number of characters to return for each item notes when
  # searching. Item notes may be very long, when returning them with
  # all the results from a search, they add quite some data to return.
  # In order to keep this low, a limit can be defined here.
  max-note-length = 180


  # This defines whether the classification form in the collective
  # settings is displayed or not. If all joex instances have document
  # classification disabled, it makes sense to hide its settings from
  # users.
  show-classification-settings = true

  # Authentication.
  auth {

    # The secret for this server that is used to sign the authenicator
    # tokens. If multiple servers are running, all must share the same
    # secret. You can use base64 or hex strings (prefix with b64: and
    # hex:, respectively).
    server-secret = "hex:caffee"

    # How long an authentication token is valid. The web application
    # will get a new one periodically.
    session-valid = "5 minutes"

    remember-me {
      enabled = true
      # How long the remember me cookie/token is valid.
      valid = "30 days"
    }
  }

  # Configures OpenID Connect (OIDC) or OAuth2 authentication. Only
  # the "Authorization Code Flow" is supported.
  #
  # Multiple authentication providers can be defined. Each is
  # configured in the array below. The `provider` block gives all
  # details necessary to authenticate against an external OIDC or
  # OAuth provider. This requires at least two URLs for OIDC and three
  # for OAuth2. When using OIDC, the `user-url` is only required if
  # the account data is to be retrieved from the user-info endpoint
  # and not from the JWT token. For the request to the `user-url`, the
  # access token is then used to authenticate at the provider. Thus,
  # it doesn't need to be validated here and therefore no `sign-key`
  # setting is needed. However, if you want to extract the account
  # information from the access token, it must be validated here and
  # therefore the correct signature key and algorithm must be
  # provided. If the `sign-key` is left empty, the `user-url` is used
  # and must be specified. If the `sign-key` is _not_ empty, the
  # response from the authentication provider is validated using this
  # key.
  #
  # After successful authentication, docspell needs to create the
  # account. For this a username and collective name is required. The
  # account name is defined by the `user-key` and `collective-key`
  # setting. The `user-key` is used to search the JSON structure, that
  # is obtained from the JWT token or the user-info endpoint, for the
  # login name to use. It traverses the JSON structure recursively,
  # until it finds an object with that key. The first value is used.
  #
  # The `collective-key` can be used in multiple ways and both can
  # work together to retrieve the full account id:
  #
  # - If it starts with `fixed:`, like "fixed:collective", the name
  #   after the `fixed:` prefix is used as collective as is. So all
  #   users are in the same collective.
  #
  # - If it starts with `lookup:`, like "lookup:collective_name", the
  #   value after the prefix is used to search the JSON response for
  #   an object with this key, just like it works with the `user-key`.
  #
  # - If it starts with `account:`, like "account:demo", it works the
  #   same as `lookup:` only that the value is interpreted as the full
  #   account name of form `collective/login`. The `user-key` value is
  #   ignored in this case.
  #
  # If these values cannot be obtained from the response, docspell
  # fails the authentication. It is then assumed that the successfully
  # authenticated user at the OP has not enough permissions to access
  # docspell.
  #
  # Below are examples for OpenID Connect (keycloak) and OAuth2
  # (github).
  openid =
    [ { enabled = false,

        # The name to render on the login link/button.
        display = "Keycloak"

        # This illustrates to use a custom keycloak setup as the
        # authentication provider. For details, please refer to the
        # keycloak documentation. The settings here assume a certain
        # configuration at keycloak.
        #
        # Keycloak can be configured to return the collective name for
        # each user in the access token. It may also be configured to
        # return it in the user info response. If it is already in the
        # access token, an additional request can be omitted. Set the
        # `sign-key` to an empty string then. Otherwise provide the
        # algo and key from your realm settings. In this example, the
        # realm is called "home".
        provider = {
          provider-id = "keycloak",
          client-id = "docspell",
          client-secret = "example-secret-439e-bf06-911e4cdd56a6",
          scope = "profile", # scope is required for OIDC
          authorize-url = "http://localhost:8080/auth/realms/home/protocol/openid-connect/auth",
          token-url = "http://localhost:8080/auth/realms/home/protocol/openid-connect/token",
          #User URL is not used when signature key is set.
          #user-url = "http://localhost:8080/auth/realms/home/protocol/openid-connect/userinfo",
          sign-key = "b64:anVzdC1hLXRlc3Q=",
          sig-algo = "RS512"
        },
        # The collective of the user is given in the access token as
        # property `docspell_collective`.
        collective-key = "lookup:docspell_collective",
        # The username to use for the docspell account
        user-key = "preferred_username"
      },
      { enabled = false,

        # The name to render on the login link/button.
        display = "Github"

        # Provider settings for using github as an authentication
        # provider. Note that this is only an example to illustrate
        # how it works. Usually you wouldn't want to let every user on
        # github in ;-).
        #
        # Github doesn't have full OpenIdConnect, but supports the
        # OAuth2 code flow (which is very similar). It mainly means,
        # that there is no standardized token to validate and get
        # information from. So the user-url must be used in this case.
        provider = {
          provider-id = "github",
          client-id = "<your github client id>",
          client-secret = "<your github client secret>",
          scope = "", # scope is not needed for github
          authorize-url = "https://github.com/login/oauth/authorize",
          token-url = "https://github.com/login/oauth/access_token",
          user-url = "https://api.github.com/user",
          sign-key = "" # this must be set empty
          sig-algo = "RS256" #unused but must be set to something
        },

        # If the authentication provider doesn't provide the
        # collective name, simply use a fixed one. This means all
        # users from this provider are in the same collective!
        collective-key = "fixed:demo",

        # Github provides the login name via the `login` property as
        # response from the user-url. This value is used to construct
        # the account in docspell.
        user-key = "login"
      }
    ]

  # This endpoint allows to upload files to any collective. The
  # intention is that local software integrates with docspell more
  # easily. Therefore the endpoint is not protected by the usual
  # means.
  #
  # For security reasons, this endpoint is disabled by default. If
  # enabled, you can choose from some ways to protect it. It may be a
  # good idea to further protect this endpoint using a firewall, such
  # that outside traffic is not routed.
  #
  # NOTE: If all protection methods are disabled, the endpoint is not
  # protected at all!
  integration-endpoint {
    enabled = false

    # The priority to use when submitting files through this endpoint.
    priority = "low"

    # The name used for the item "source" property when uploaded
    # through this endpoint.
    source-name = "integration"

    # IPv4 addresses to allow access. An empty list, if enabled,
    # prohibits all requests. IP addresses may be specified as simple
    # globs: a part marked as `*' matches any octet, like in
    # `192.168.*.*`. The `127.0.0.1' (the default) matches the
    # loopback address.
    allowed-ips {
      enabled = false
      ips = [ "127.0.0.1" ]
    }

    # Requests are expected to use http basic auth when uploading
    # files.
    http-basic {
      enabled = false
      realm = "Docspell Integration"
      user = "docspell-int"
      password = "docspell-int"
    }

    # Requests are expected to supply some specific header when
    # uploading files.
    http-header {
      enabled = false
      header-name = "Docspell-Integration"
      header-value = "some-secret"
    }
  }

  # This is a special endpoint that allows some basic administration.
  #
  # It is intended to be used by admins only, that is users who
  # installed the app and have access to the system. Normal users
  # should not have access and therefore a secret must be provided in
  # order to access it.
  #
  # This is used for some endpoints, for example:
  # - re-create complete fulltext index:
  #   curl -XPOST -H'Docspell-Admin-Secret: xyz' http://localhost:7880/api/v1/admin/fts/reIndexAll
  admin-endpoint {
    # The secret. If empty, the endpoint is disabled.
    secret = ""
  }

  # Configuration of the full-text search engine.
  full-text-search {
    # The full-text search feature can be disabled. It requires an
    # additional index server which needs additional memory and disk
    # space. It can be enabled later any time.
    #
    # Currently the SOLR search platform is supported.
    enabled = false

    # Configuration for the SOLR backend.
    solr = {
      # The URL to solr
      url = "http://localhost:8983/solr/docspell"
      # Used to tell solr when to commit the data
      commit-within = 1000
      # If true, logs request and response bodies
      log-verbose = false
      # The defType parameter to lucene that defines the parser to
      # use. You might want to try "edismax" or look here:
      # https://solr.apache.org/guide/8_4/query-syntax-and-parsing.html#query-syntax-and-parsing
      def-type = "lucene"
      # The default combiner for tokens. One of {AND, OR}.
      q-op = "OR"
    }
  }

  # Configuration for the backend.
  backend {
    # Enable or disable debugging for e-mail related functionality. This
    # applies to both sending and receiving mails. For security reasons
    # logging is not very extensive on authentication failures. Setting
    # this to true, results in a lot of data printed to stdout.
    mail-debug = false

    # The database connection.
    #
    # By default a H2 file-based database is configured. You can
    # provide a postgresql or mariadb connection here. When using H2
    # use the PostgreSQL compatibility mode and AUTO_SERVER feature.
    jdbc {
      url = "jdbc:h2://"${java.io.tmpdir}"/docspell-demo.db;MODE=PostgreSQL;DATABASE_TO_LOWER=TRUE;AUTO_SERVER=TRUE"
      user = "sa"
      password = ""
    }

    # Configuration for registering new users.
    signup {

      # The mode defines if new users can signup or not. It can have
      # three values:
      #
      # - open: every new user can sign up
      # - invite: new users can sign up only if they provide a correct
      #   invitation key. Invitation keys can be generated by the
      #   server.
      # - closed: signing up is disabled.
      mode = "open"

      # If mode == 'invite', a password must be provided to generate
      # invitation keys. It must not be empty.
      new-invite-password = ""

      # If mode == 'invite', this is the period an invitation token is
      # considered valid.
      invite-time = "3 days"
    }

    files {
      # Defines the chunk size (in bytes) used to store the files.
      # This will affect the memory footprint when uploading and
      # downloading files. At most this amount is loaded into RAM for
      # down- and uploading.
      #
      # It also defines the chunk size used for the blobs inside the
      # database.
      chunk-size = 524288

      # The file content types that are considered valid. Docspell
      # will only pass these files to processing. The processing code
      # itself has also checks for which files are supported and which
      # not. This affects the uploading part and can be used to
      # restrict file types that should be handed over to processing.
      # By default all files are allowed.
      valid-mime-types = [ ]
    }
  }
}