Skip to main content
Version: 3.x.x

Server configuration

As the Server is based on Spring framework, it follows its configuration standards. You can configure Tolgee by providing a configuration file, provide configuration properties as command line arguments when you run Tolgee with java -jar command, or as environment variables.

Example configuration files:

enabled: true
initial-password: admin
initial-username: admin
jwt-secret: my_jwt_secret
api-key: my_google_api_key
auth: true
from: Tolgee <>
password: 'omg/my/password'
port: 465
ssl-enabled: true

Server settings

Prefix: server

These properties are used to configure the server.

  • port

    Port on which Tolgee exposes itself. (default: 8080)

Spring settings

Prefix: spring

These properties are used to configure Spring framework.

Data source settings

Prefix: spring.datasource

Since Tolgee is built on Spring framework, you have to edit following configuration props to configure its database connection. These properties can be omitted when using Postgres autostart, which is enabled by default.

  • url

    The url of the datasource in format jdbc:postgresql://<host>:<port>/<dbname>. e.g. jdbc:postgresql://db:5432/postgres

  • username

    Database username. e.g. postgres

  • password

    Database password. e.g. postgres


Prefix: tolgee

Configuration specific to Tolgee.

  • file-storage-url

    Public base path where files are accessible. Used by the user interface.

  • front-end-url

    Public URL where Tolgee is accessible. Used to generate links to Tolgee (e.g. email confirmation link).

  • max-screenshots-per-key

    Maximum amount of screenshots which can be uploaded per API key. (default: 20)

  • max-translation-text-length

    Maximum length of translations. (default: 10000)

  • max-upload-file-size

    Maximum size of uploaded files (in kilobytes). (default: 51200 ≈ 50MB)


Prefix: tolgee.authentication

Configuration of Tolgee's authentication.

  • enabled

    Whether authentication is enabled. When authentication is disabled, there are no login screen and no permission control. Users get automatically logged in as the administrator account of the Tolgee instance. This is very useful, when you want to use Tolgee on your local machine, or you just want to test it. (default: true when running with Java directly, false when running via Docker.)

  • initial-password

    Password of initial user. If unspecified, a random password will be generated and stored in the initial.pwd file, located at the root of Tolgee's data path.


    Once set, you don't need to set this property anymore, and it is recommended you unset it so the password is not stored in plaintext in config files.

    If you set this field to something else, the initial user's password will be updated unless the password was updated once via the Tolgee web UI.

  • initial-username

    Username of initial user.


    Tolgee will ask for an email instead of a username - don't worry, just give it the username specified here.

    (default: admin)

  • jwt-expiration

    Expiration time of generated JWT tokens in milliseconds. (default: 604800000 = 7 days)

  • jwt-secret

    Secret used to sign JWT authentication tokens with. It will be generated automatically, if not provided. You will be fine with 64 characters long random string.


    When running multiple replicas, it is required to set it, or you will be constantly logged out otherwise.

  • jwt-super-expiration

    Expiration time of generated JWT tokens for superuser in milliseconds. (default: 3600000 = 1 hour)

  • native-enabled

    Whether to enable Tolgee-native authentication and registration. When set to false, users will only be able to register and login via third-party SSO options (e.g. OAuth). (default: true)

  • needs-email-verification

    Whether users need to verify their email addresses when creating their account. Requires a valid SMTP configuration. (default: false)

  • registrations-allowed

    Whether users are allowed to register on Tolgee. When set to false, existing users must send invites to projects to new users for them to be able to register. (default: false)

  • secured-image-retrieval

    Whether image assets should be protected by Tolgee. When enabled, all images are served with an access token valid for a set period of time to prevent unauthorized access to images. (default: false)

  • secured-image-timestamp-max-age

    Expiration time of a generated image access token in milliseconds. (default: 600000 = 10 minutes)

  • user-can-create-organizations

    Whether regular users are allowed to create organizations. When false, only administrators can create organizations. By default, when the user has no organization, one is created for them; this doesn't apply when this setting is set to false. In that case, the user without organization has no permissions on the server. (default: true)


Prefix: tolgee.authentication.github


GitHub authentication can be used in combination with native authentication.

  • authorization-url

    URL to the OAuth authorization screen. Useful if you want to authenticate against a self-hosted GitHub Enterprise Server. (default:

  • client-id

    OAuth Client ID, obtained in GitHub administration.

  • client-secret

    OAuth Client secret, obtained in GitHub administration.

  • user-url

    URL to GitHub's /user API endpoint. Useful if you want to authenticate against a self-hosted GitHub Enterprise Server. (default:



The following instructions explain how to set up Google OAuth. Setting up OAuth 2.0.

  • authorization-url

    URL to Google /token API endpoint. This usually does not need to be changed. (default:

  • client-id

    OAuth Client ID, obtained in Google Cloud Console.

  • client-secret

    OAuth Client secret, obtained in Google Cloud Console.

  • user-url

    URL to Google /userinfo API endpoint. This usually does not need to be changed. (default:

  • workspace-domain

    The registration can be limited to users of a Google Workspace domain. Multiple Google Workspace domains can be separated by a comma ,. If nothing is set, anyone can log in with their Google account.


Prefix: tolgee.authentication.oauth2

OAuth 2.0 is the industry-standard protocol for authorization. This enables the integration of a wide range of authorization providers into tolgee, such as Auth0, KeyCloak, Okta and others.

  • authorization-url

    URL to OAuth2 authorize API endpoint. This endpoint will exposed to the frontend.

  • client-id

    OAuth2 Client ID

  • client-secret

    OAuth2 Client secret

  • scopes

    Oauth2 scopes (as list) Tolgee absolutely requires rights to view the email and user information (also known as openid data). In most cases the scopes openid email profile is used for this. (But can also be different depending on the provider) (default: [])

  • token-url

    URL to OAuth2 token API endpoint.

  • user-url

    URL to OAuth2 userinfo API endpoint.

  • user-can-create-projects

    Removed in: 2.33.0

    Whether regular users are allowed to create projects. When disabled, only administrators can create projects (default: true)

  • create-initial-user

    Removed in: 3.31.0

    If true, Tolgee creates initial user on first start-up. (default: true)

  • ldap.*

    Removed in: 3.31.0

    LDAP-related settings.

Batch operations

Prefix: tolgee.batch

Configuration of batch operations.

  • concurrency

    How many parallel jobs can be run at once on single Tolgee instance (default: 1)


Prefix: tolgee.cache

At the expense of higher memory footprint, Tolgee can use a cache to reduce the stress on the database and fetch the data it needs faster. Cache is also used to track certain states, such as rate limits.

  • caffeine-max-size

    Maximum size of the Caffeine cache. When exceeded, some entries will be purged from cache. Set to -1 to disable size limitation. This has no effect when Redis cache is used. See Caffeine's documentation about size-based eviction (default: -1)

  • clean-on-startup

    Whether to clean the cache on Tolgee startup (default: true)

  • default-ttl

    TTL of cache data, in milliseconds. (default: 7200000 ≈ 2 hours)

  • enabled

    Whether Tolgee should use a cache. (default: false)

  • use-redis

    Whether Tolgee should use Redis to store cache data instead of storing it in-memory.


    In a distributed environment, you should use a Redis server to ensure consistent enforcement of rate limits, as they heavily rely on cache. For a simple single-node deployment, in-memory cache is sufficient.


    Tolgee uses Redisson to interface with the Redis server. You can find the properties Redisson expects here.

    (default: false)

Content Delivery

Prefix: tolgee.content-delivery

These properties are used to configure default server content delivery storage.

  • public-url-prefix

    The root path where the content is accessible by the public. If this property is not null, content delivery will be enabled on your server.





  • connection-string
  • container-name


File storage

Prefix: tolgee.file-storage

Configuration of Tolgee file storage.

  • fs-data-path

    Path to directory where Tolgee will store its files. (default: ~/.tolgee/ , with docker /data/)


Prefix: tolgee.file-storage.s3

Tolgee supports storing its files on an S3-compatible storage server. When enabled, Tolgee will store all its files on the S3 server rather than in filesystem.

  • access-key

    Access key for the S3 server. (optional if you are authenticating with a different method, like STS Web Identity)

  • bucket-name

    Name of the bucket where Tolgee will store its files.

  • enabled

    Whether S3 is enabled. If enabled, you need to set all remaining properties below. (default: false)

  • endpoint

    Has to be set to a service endpoint:

  • secret-key

    Secret key for the access key. (optional if you are authenticating with a different method, like STS Web Identity)

  • signing-region

    Has to be set to a signing region:


Prefix: tolgee.import

Properties for importing data to Tolgee and bulk-imports exported json files in the database during startup. Useful to quickly provision a development server, and used for testing.

  • base-language-tag

    The language tag of the base language of the imported project (for importing data on startup). (default: en)

  • create-implicit-api-key

    Whether an implicit API key should be created when importing data on startup.

    The key is built with a predictable format: ${lowercase filename (without extension)}-${initial username}-imported-project-implicit


    While this is useful for tests, make sure to keep this disabled if you're importing projects on a production server as trying this predictable key may be the first thing an attacker will attempt to gain unauthorized access!

    (default: false)

  • dir

    File path of the directory where the files to import on startup are located.


    Your folder structure should look like: importDir └─Project # the foler name is the project name └─validation # the foler name is namespace ├─ en.json # the file name is the target language └─ de.json # second project language

  • store-files-for-debugging

    If true, uploaded files will be stored in configured file storage for future debugging. Such data is not automatically removed after successful import. You have to clean-up manually! (default: false)

Machine Translation

Prefix: tolgee.machine-translation

Configuration of Machine Translation services.

  • free-credits-amount

    Amount of machine translations users of the Free tier can request per month. Used by Tolgee Cloud, see pricing. Set to -1 to disable credit-based limitation. (default: -1)

AWS Amazon Translate


See AWS's Amazon Translate page for more information and applicable pricing.

  • access-key

    AWS access key. (optional if you are authenticating with a different method, like STS Web Identity)

  • default-enabled

    Whether AWS-powered machine translation is enabled. (default: true)

  • default-primary

    Whether to use AWS Amazon Translate as a primary translation engine. (default: false)

  • enabled

    If you are authenticating using a different method than explicit access key and secret key, which implicitly enable AWS Translate, you should enable AWS Translate using this option.

  • region

    AWS region. (default: eu-central-1)

  • secret-key

    AWS secret key. (optional if you are authenticating with a different method, like STS Web Identity)

Azure Cognitive Translation

Prefix: tolgee.machine-translation.azurecognitive

See Azure Cognitive Translation page for more information and applicable pricing.

  • auth-key

    Azure Cognitive Translation auth key.

  • default-enabled

    Whether Azure Cognitive Translation is enabled. (default: true)

  • default-primary

    Whether to use Azure Cognitive Translation as a primary translation engine. (default: false)

  • region

    Azure Cognitive Translation region.

Baidu Translate


See Baidu's page (in Chinese) for more information and applicable pricing.

  • action

    Whether the resulting translation should be changed according to the user-defined dictionary. The dictionary used can be modified at Manage Terms (login required). (default: false)

  • app-id

    Baidu Translate App ID.

  • app-secret

    Baidu Translate Secret key.

  • default-enabled

    Whether Baidu-powered machine translation is enabled. (default: true)

  • default-primary

    Whether to use Baidu Translate as a primary translation engine. (default: false)


Prefix: tolgee.machine-translation.deepl

See DeepL's page for more information and applicable pricing.

  • auth-key

    DeepL auth key. Both key types (commercial and free) are supported.

  • default-enabled

    Whether DeepL-powered machine translation is enabled. (default: true)

  • default-primary

    Whether to use DeepL as a primary translation engine. (default: false)

Google Cloud Translation


See Google Cloud Translation page for more information and applicable pricing.

  • api-key

    Google Cloud Translation API key.

  • default-enabled

    Whether Google-powered machine translation is enabled. (default: true)

  • default-primary

    Whether to use Google Cloud Translation as a primary translation engine. (default: true)


Prefix: tolgee.machine-translation.tolgee

  • default-enabled
  • default-primary

Postgres autostart

Prefix: tolgee.postgres-autostart

Defines whether and how is PostgreSQL started on Tolgee startup.

  • container-name

    The container name of the Postgres container. This setting is applicable only for DOCKER mode. (default: tolgee_postgres)

  • database-name

    The name of the database created to store Tolgee data. (default: postgres)

  • enabled

    Whether to start PostgreSQL on Tolgee startup. (default: true)

  • max-wait-time

    The max time to wait for running postgres in seconds. (default: 300)

  • mode

    How is Tolgee running PostgreSQL.


    • DOCKER - Tolgee tries to run Postgres Docker container in your machine. This is default option when running Tolgee using Java. See Running with Java.
    • EMBEDDED - Tolgee tries to run it's embedded PostgreSQL which is bundled in the tolgee/tolgee Docker image. (default: DOCKER)
  • password

    Database password to bootstrap Postgres with. (default: postgres)

  • port

    The port of Postgres to listen on host machine. This setting is applicable only for DOCKER mode. (default: 25432)

  • stop

    When true, Tolgee will stop the Postgres container on Tolgee shutdown. This setting is applicable only for DOCKER mode. (default: true)

  • user

    Database user to bootstrap Postgres with. (default: postgres)

Rate limits

Prefix: tolgee.rate-limits

Configuration of the rate limit behavior of the server. Rate limits are used to protect against server overload and/or abuse, and are enabled by default.

You can disable global, per-endpoint and auth-related rate limits, or configure global rate limits. Per-endpoint and auth-related rate limits are fixed and cannot be configured.

  • authentication-limits

    Control whether per-endpoint limits on authentication-related endpoints are enabled or not.


    It is strongly recommended to keep these limits enabled. They act as a protection layer against brute-force attacks on the login (and register) prompt.

    (default: true)

  • enabled

    To turn all rate limits off, set this value to false.


    This field is deprecated and will be removed with Tolgee 4. If set to false, it will take priority over the more granular global-limits, endpoint-limits and authentication-limits and all limits will be disabled.

    (default: true)

  • endpoint-limits

    Control whether per-endpoint limits on the API are enabled or not. Does not affect authentication-related endpoints, these are controlled by authentication-limits. (default: true)

  • global-limits

    Control whether global limits on the API are enabled or not. (default: true)

  • ip-request-limit

    Amount of requests an IP address can do in a single time window. (default: 20000)

  • ip-request-window

    Size, in milliseconds, of the time window for IP-based limiting. (default: 300000 = 5 minutes)

  • user-request-limit

    Amount of requests a user can do in a single time window. (default: 400)

  • user-request-window

    Size, in milliseconds, of the time window for user-based limiting. (default: 60000 = 1 minute)


Prefix: tolgee.recaptcha

When configured, reCAPTCHA v3 is used to protect the sign up page against bots. By default, reCAPTCHA is disabled.

To enable it, you first need to register a new site on reCAPTCHA. Make sure to select reCAPTCHA v3 when registering your site.

  • secret-key

    Secret key for communication between your site and reCAPTCHA.

  • site-key

    Site key for use the HTML code your site serves to users.


Prefix: tolgee.sentry

Tolgee uses Sentry for error reporting.

  • client-dsn

    Client DSN. If unset, error reporting is disabled on the server.

  • server-dsn

    Server DSN. If unset, error reporting is disabled on the server.

  • traces-sample-rate

    Sample rate for Sentry traces. If unset, traces are disabled on the server.


Prefix: tolgee.smtp

Configuration of SMTP server used to send emails to your users like password reset links or notifications.

For AWS SES it would look like this:
tolgee.smtp.from=Tolgee <no-reply@tolgee.yourserver.something>
  • auth

    Whether authentication is enabled. (default: false)

  • from

    The sender name and address in standard SMTP format.

  • host

    SMTP server host

  • password

    Password for SMTP authentication

  • port

    SMTP server port (default: 25)

  • ssl-enabled

    Whether SSL is enabled. (default: false)

  • tls-enabled

    Whether TLS is enabled. (default: false)

  • tls-required

    Whether SSL is required. (default: false)

  • username

    The username for SMTP authentication


Prefix: tolgee.telemetry

By default, self-hosted instances send anonymous data about usage to help us improve Tolgee.


This was added in Tolgee Platform v3.23.0

Once a day we collect following data

  • number of projects
  • number of languages
  • number of translations
  • number of users

We don't collect any other data. Please leave telemetry enabled to help us improve Tolgee.

  • enabled

    Whether telemetry is enabled (default: true)


Prefix: tolgee.websocket

Configuration specific to the use of Websocket.

  • use-redis

    Whether to use Redis for Websocket events (default: false)

Full configuration example

port: 8080
max-screenshots-per-key: 20
max-translation-text-length: 10000
max-upload-file-size: 51200
enabled: true
initial-username: admin
jwt-expiration: 604800000
jwt-super-expiration: 3600000
native-enabled: true
needs-email-verification: false
registrations-allowed: false
secured-image-retrieval: false
secured-image-timestamp-max-age: 600000
user-can-create-organizations: true
scopes: []
concurrency: 1
caffeine-max-size: -1
clean-on-startup: true
default-ttl: 7200000
enabled: false
use-redis: false
fs-data-path: ~/.tolgee/
enabled: false
base-language-tag: en
create-implicit-api-key: false
store-files-for-debugging: false
free-credits-amount: -1
default-enabled: true
default-primary: false
region: eu-central-1
default-enabled: true
default-primary: false
action: false
default-enabled: true
default-primary: false
default-enabled: true
default-primary: false
default-enabled: true
default-primary: true
default-enabled: true
default-primary: true
container-name: tolgee_postgres
database-name: postgres
enabled: true
max-wait-time: 300
mode: DOCKER
password: postgres
port: 25432
stop: true
user: postgres
authentication-limits: true
enabled: true
endpoint-limits: true
global-limits: true
ip-request-limit: 20000
ip-request-window: 300000
user-request-limit: 400
user-request-window: 60000
auth: false
port: 25
ssl-enabled: false
tls-enabled: false
tls-required: false
enabled: true
use-redis: false