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:

YAML
.env
application.properties

config.yaml
tolgee:
  authentication:
    initial-password: admin
    initial-username: admin
    jwt-secret: my_jwt_secret
  machine-translation:
    google:
      api-key: my_google_api_key
  smtp:
    auth: true
    from: Tolgee <no-reply@mydomain.com>
    host: email-smtp.regional-region.amazonaws.com
    password: 'omg/my/password'
    port: 465
    ssl-enabled: true
    username: user@company.com

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

Tolgee

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)

Authentication

Prefix: tolgee.authentication

Configuration of Tolgee's authentication.

create-initial-user
If true, Tolgee creates initial user on first start-up. (default: true)
enabled
Whether authentication is enabled. If not, Tolgee will create implicit user on first startup and will automatically log you in. No login page shows, no permissions are managed. This is very useful, when you want to use Tolgee on your local machine, or you just want to test it. (default: true)
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.
initial-username
Username of initial user. (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. Generated automatically, if not provided. If running multiple replicas, it's required to set it or otherwise you will be constantly logged out.
jwt-super-expiration
Expiration time of generated JWT tokens for superuser in milliseconds. (default: 3600000 ≈ 1 hour)
native-enabled
Whether user credentials are stored in Tolgee's database. If you would like to use LDAP, set this to false. (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
Enable/disable sign ups into Tolgee. (default: false)
secured-image-retrieval
Whether image assets should be protected by Tolgee. When enabled, all images are served with a secure 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 seconds. (default: 600000 ≈ one week)
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)

GitHub

Prefix: tolgee.authentication.github

info

GitHub authentication can be used in combination with LDAP or native authentication.

authorization-url
URL to the OAuth authorization screen. Useful if you want to authenticate against a self-hosted GitHub Enterprise Server. (default: https://github.com/login/oauth/access_token)
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: https://api.github.com/user)

Google

Prefix: tolgee.authentication.google

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: https://oauth2.googleapis.com/token)
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: https://www.googleapis.com/oauth2/v3/userinfo)
workspace-domain
The registration can be limited to users of a Google Workspace domain. If nothing is set, anyone can log in with their Google account.

LDAP

Prefix: tolgee.authentication.ldap

danger

This feature is experimental!

info

LDAP authentication can be used in combination with GitHub or native authentication.

Tolgee can use a LDAP server to authenticate users. This is very useful if you already use LDAP as a primary mean of authentication for other services.

base-dn
LDAP base DN. For example dc=example,dc=com
enabled
Whether LDAP authentication is enabled. If enabled, you need to set all remaining properties below. (default: false)
port
LDAP server host
principal-password
LDAP password for the manager DN
security-principal
LDAP manager DN. For example cn=admin,dc=example,dc=com
urls
LDAP server URLs. For example ldap://localhost:389
user-dn-pattern
LDAP user search filter. For example (uid={0})

OAuth2

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)

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)

Cache

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)
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.
info
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.
info
Tolgee uses Redisson to interface with the Redis server. You can find the properties Redisson expects here.

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/)

S3

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: https://docs.aws.amazon.com/general/latest/gr/s3.html
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: https://docs.aws.amazon.com/general/latest/gr/s3.html

Import

Prefix: tolgee.import

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 projects. (default: en)
create-implicit-api-key
Whether an implicit API key should be created.
The key is built with a predictable format: ${lowercase filename (without extension)}-${initial username}-imported-project-implicit
danger
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!
dir
File path of the directory where the file to import are located.

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

Prefix: tolgee.machine-translation.aws

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

Prefix: tolgee.machine-translation.baidu

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)

DeepL

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)
formality
Whether the translated text should lean towards formal or informal language. See DeepL's documentation for supported languages and details. (default: default)

Google Cloud Translation

Prefix: tolgee.machine-translation.google

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)

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)
mode
How is Tolgee running PostgreSQL.
Options:
- 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)
user
Database user to bootstrap Postgres with. (default: postgres)

Rate limits

Prefix: tolgee.rate-limits

Configuration of rate limits. By default Tolgee Platform limits requests to endpoints according to these rules:

Single IP is not allowed to request more than 20 000 times in 5 minutes
Single IP is not allowed to request public endpoints (authentication, sign-ups) more than 1000 times per hour
Single authenticated user cannot do more than 400 requests per minute

enabled
To turn these rate limits off, set this value to false. (default: true)

reCAPTCHA

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.

Sentry

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.

SMTP

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.host=email-smtp.eu-central-1.amazonaws.com
tolgee.smtp.username=*****************
tolgee.smtp.password=*****************
tolgee.smtp.port=465
tolgee.smtp.auth=true
tolgee.smtp.ssl-enabled=true
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

Telemetry

Prefix: tolgee.telemetry

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

info

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)

Websocket

Prefix: tolgee.websocket

Configuration specific to the use of Websocket.

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

Full configuration example

YAML
.env
application.properties

Details

config.yaml
server:
  port: 8080
spring:
  datasource:
    url:
    username:
    password:
tolgee:
  file-storage-url:
  front-end-url:
  max-screenshots-per-key: 20
  max-translation-text-length: 10000
  max-upload-file-size: 51200
  authentication:
    create-initial-user: true
    enabled: true
    initial-password:
    initial-username: admin
    jwt-expiration: 604800000
    jwt-secret:
    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
    github:
      authorization-url: https://github.com/login/oauth/access_token
      client-id:
      client-secret:
      user-url: https://api.github.com/user
    google:
      authorization-url: https://oauth2.googleapis.com/token
      client-id:
      client-secret:
      user-url: https://www.googleapis.com/oauth2/v3/userinfo
      workspace-domain:
    ldap:
      base-dn:
      enabled: false
      port:
      principal-password:
      security-principal:
      urls:
      user-dn-pattern:
    oauth2:
      authorization-url:
      client-id:
      client-secret:
      scopes: []
      token-url:
      user-url:
  batch:
    concurrency: 1
  cache:
    caffeine-max-size: -1
    default-ttl: 7200000
    enabled: false
    use-redis: false
  file-storage:
    fs-data-path: ~/.tolgee/
    s3:
      access-key:
      bucket-name:
      enabled: false
      endpoint:
      secret-key:
      signing-region:
  import:
    base-language-tag: en
    create-implicit-api-key: false
    dir:
  machine-translation:
    free-credits-amount: -1
    aws:
      access-key:
      default-enabled: true
      default-primary: false
      enabled:
      region: eu-central-1
      secret-key:
    azure:
      auth-key:
      default-enabled: true
      default-primary: false
      region:
    baidu:
      action: false
      app-id:
      app-secret:
      default-enabled: true
      default-primary: false
    deepl:
      auth-key:
      default-enabled: true
      default-primary: false
      formality: default
    google:
      api-key:
      default-enabled: true
      default-primary: true
  postgres-autostart:
    container-name: tolgee_postgres
    database-name: postgres
    enabled: true
    mode: DOCKER
    password: postgres
    port: 25432
    user: postgres
  rate-limits:
    enabled: true
  recaptcha:
    secret-key:
    site-key:
  sentry:
    client-dsn:
    server-dsn:
    traces-sample-rate:
  smtp:
    auth: false
    from:
    host:
    password:
    port: 25
    ssl-enabled: false
    tls-enabled: false
    tls-required: false
    username:
  telemetry:
    enabled: true
  websocket:
    use-redis: false

Server settings​

port​

Spring settings​

Data source settings​

url​

username​

password​

Tolgee​

file-storage-url​

front-end-url​

max-screenshots-per-key​

max-translation-text-length​

max-upload-file-size​

Authentication​

create-initial-user​

enabled​

initial-password​

initial-username​

jwt-expiration​

jwt-secret​

jwt-super-expiration​

native-enabled​

needs-email-verification​

registrations-allowed​

secured-image-retrieval​

secured-image-timestamp-max-age​

user-can-create-organizations​

GitHub​

authorization-url​

client-id​

client-secret​

user-url​

Google​

authorization-url​

client-id​

client-secret​

user-url​

workspace-domain​

LDAP​

base-dn​

enabled​

port​

principal-password​

security-principal​

urls​

user-dn-pattern​

OAuth2​

authorization-url​

client-id​

client-secret​

scopes​

token-url​

user-url​

user-can-create-projects​

Batch operations​

concurrency​

Cache​

caffeine-max-size​

default-ttl​

enabled​

use-redis​

File storage​

fs-data-path​

S3​

access-key​

bucket-name​

enabled​

endpoint​

secret-key​

signing-region​

Import​

base-language-tag​

create-implicit-api-key​

dir​

Machine Translation​

free-credits-amount​

AWS Amazon Translate​

access-key​

default-enabled​

default-primary​

Server settings

`port`

Spring settings

Data source settings

`url`

`username`

`password`

Tolgee

`file-storage-url`

`front-end-url`

`max-screenshots-per-key`

`max-translation-text-length`

`max-upload-file-size`

Authentication

`create-initial-user`

`enabled`

`initial-password`

`initial-username`

`jwt-expiration`

`jwt-secret`

`jwt-super-expiration`

`native-enabled`

`needs-email-verification`

`registrations-allowed`

`secured-image-retrieval`

`secured-image-timestamp-max-age`

`user-can-create-organizations`

GitHub

`authorization-url`

`client-id`

`client-secret`

`user-url`

Google

`authorization-url`

`client-id`

`client-secret`

`user-url`

`workspace-domain`

LDAP

`base-dn`

`enabled`

`port`

`principal-password`

`security-principal`

`urls`

`user-dn-pattern`

OAuth2

`authorization-url`

`client-id`

`client-secret`

`scopes`

`token-url`

`user-url`

`user-can-create-projects`

Batch operations

`concurrency`

Cache

`caffeine-max-size`

`default-ttl`

`enabled`

`use-redis`

File storage

`fs-data-path`

S3

`access-key`

`bucket-name`

`enabled`

`endpoint`

`secret-key`

`signing-region`

Import

`base-language-tag`

`create-implicit-api-key`

`dir`

Machine Translation

`free-credits-amount`

AWS Amazon Translate

`access-key`

`default-enabled`

`default-primary`