Skip to main content
Version: 2.x.x

Server configuration

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

server.port​

Port on which Tolgee exposes itself (default: 8080)

Data source settings​

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

spring.datasource.url​

The url of the datasource in format jdbc:postgresql://<host>:<port>/<dbname>.

e.g. jdbc:postgresql://db:5432/postgres

spring.datasource.username​

Database username. e.g. postgres

spring.datasource.password​

Database password. e.g. postgres

Tolgee​

Configuration specific to Tolgee

tolgee.front-end-url​

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

tolgee.file-storage-url​

Public base path where files are accessible. Used by the user interface. (default: same origin, at the root).

tolgee.max-upload-file-size​

Maximum size of uploaded files (in kilobytes). (default: 2048 ≈ 2MB)

tolgee.max-screenshots-per-key​

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

tolgee.max-translation-text-length​

Maximum length of translations. (default: 10000)

File storage​

Prefix: tolgee.file-storage

fs-data-path​

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

s3.enabled​

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 on disk. (default: false)

When enabled, you will need to set the following configuration properties as well:

Authentication​

Prefix: tolgee.authentication

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: false)

jwt-secret​

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

jwt-expiration​

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

native-enabled​

Whether user credentials are stored in Tolgee's database. If you would like to use LDAP, set this to false. (default true)

registrations-allowed​

Enable/disable sign ups into Tolgee. (default: false)

needs-email-verification​

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

create-initial-user​

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

initial-username​

Username of initial user. (default: false)

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. (default: null)

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 ≈ a week)

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)

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 user-can-create-organizations = false. In that case, the user without organization has no permissions on the server. (default: true)

GitHub authentication​

Prefix: tolgee.authentication.github

info

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

client-id​

OAuth Client ID, obtained in GitHub administration. (default: null)

client-secret​

OAuth Client secret, obtained in GitHub administration. (default: null)

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)

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 authentication​

Prefix: tolgee.authentication.google

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

client-id​

OAuth Client ID, obtained in Google Cloud Console. (default: null)

client-secret​

OAuth Client secret, obtained in Google Cloud Console. (default: null)

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. (default: null)

authorization-url​

URL to Google /token API endpoint. This usually does not need to be changed. (default: https://oauth2.googleapis.com/token)

user-url​

URL to Google /userinfo API endpoint. This usually does not need to be changed. (default: https://www.googleapis.com/oauth2/v3/userinfo)

OAuth2 authentication​

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.

client-id​

OAuth2 Client ID (default: null)

client-secret​

OAuth2 Client secret (default: null)

scopes​

Oauth2 scopes (as list) (default: null)

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)

authorization-url​

URL to OAuth2 authorize API endpoint. This endpoint will exposed to the frontend. (default: null)

token-url​

URL to OAuth2 token API endpoint. (default: null)

user-url​

URL to OAuth2 userinfo API endpoint. (default: null)

LDAP authentication​

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.

enabled​

Whether LDAP authentication is enabled. (default: false) When enabled, you will need to set the following common LDAP properties:

  • urls
  • port
  • base-dn
  • security-principal
  • principal-password
  • user-dn-pattern

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.

Then, you simply need to set the following configuration properties:

  • site-key
  • secret-key

Postgres autostart​

Prefix: tolgee.postgres-autostart

info

This feature was added in v2.

Defines, whether and how is PostgreSQL started on Tolgee startup.

enabled​

Is PostgreSQL run on startup? Defaults to 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.

user​

Database user to bootstrap Postgres with. Defaults to postgres

password​

Database password to bootstrap Postgres with. Defaults to postgres

database-name​

The name of the database created to store Tolgee data. Defaults to postgres

port​

The port of Postgres to listen on host machine. This setting is applicable only for DOCKER mode. Defaults to 25432.

container-name​

This setting is applicable only for DOCKER mode. Defaults to tolgee-postgres.

Rate Limits​

Prefix: tolgee.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 of, set this value to false. Defaults to true

SMTP​

To allow Tolgee to send emails to your users like password reset links or notifications, configure these properties. These properties are prefixed with tolgee.smtp.

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>

host​

SMTP host

username​

The username for SMTP authentication

password​

Password for SMTP authentication

port​

SMTP port

auth​

Whether authentication is enabled. (default: false)

tls-enabled​

Whether TLS is enabled. (default: false)

ssl-enabled​

Whether SSL is enabled. (default: false)

tls-required​

Whether SSL is required. (default: false)

from​

The sender name and address in standard SMTP format.

Machine translation​

Prefix: tolgee.machine-translation

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)

Google Cloud's Cloud Translation​

Prefix: tolgee.machine-translation.google

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

default-enabled​

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

default-primary​

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

api-key​

Google Cloud API key.

Amazon Translate​

Prefix: tolgee.machine-translation.aws

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

default-enabled​

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

default-primary​

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

access-key​

AWS access key.

secret-key​

AWS secret key.

region​

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

DeepL Translate​

Prefix: tolgee.machine-translation.deepl

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

default-enabled​

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

default-primary​

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

auth-key​

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

formality​

Whether the translated text should lean towards formal or informal language. See DeepL's documentation for supported languages and details. (default: default)

Socket.IO​

Prefix: tolgee.socket-io

Tolgee exposes a Socket.IO server to allow you to get realtime data modification events.

enabled​

Whether the Socket.IO server is enabled. (default: true)

port​

Port the Socket.IO server will listen on. (default: 9090)

host​

Host the Socket.IO server will listen on. (default: 0.0.0.0)

use-redis​

Whether Tolgee should use Redis to keep track of connected clients. Useful if you have multiple instances of Tolgee, to ensure consistent broadcast of events. (default: false)

info

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

external-url​

Public URL where the Socket.IO server is available. Exposed to clients via the public configuration API endpoint. (default: null)

allowed-transports​

Array of allowed Socket.IO transport methods. (default: [ "websocket", "polling" ]). Refer to the Socket.IO documentation for more information.

tip

To configure an array via properties, you need to use the [index] notation:

tolgee.socket-io.allowed-transports[0]=websocket
tolgee.socket-io.allowed-transports[1]=polling

See Spring's documentation for more information.

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.

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. (default: false)

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.

default-ttl​

TTL of cache data, in milliseconds. (default: 120 * 60 * 1000 = 2 hours)

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 for more information. (default: -1)

Sentry​

Prefix: tolgee.sentry

Tolgee uses Sentry for error reporting.

server-dsn​

Server DSN. If unset, error reporting is disabled on the server. (default: null)

client-dsn​

Client DSN. If unset, error reporting is disabled on the client. (default: null)

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.

dir​

File path of the directory where the file to import are located.

create-implicit-api-key​

Whether an implicit API key should be created. (default: false)

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!

.env example​

Example .env file which you can start with:

JAVA_OPTS="-Xms128m -Xmx1024m"
########## JWT #############
tolgee.authentication.jwt-secret=...

########## Data source #############
spring.datasource.url=jdbc:postgresql://db:5432/postgres
spring.datasource.username=postgres
spring.datasource.password=postgres

########## NATIVE #############
tolgee.authentication.registrations-allowed=false

######### SMTP ###########
tolgee.smtp.host=
tolgee.smtp.username=
tolgee.smtp.password=
tolgee.smtp.port=
tolgee.smtp.auth=
tolgee.smtp.ssl-enabled=
tolgee.smtp.from=