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
tolgee:
authentication:
enabled: true
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-demo-for-initial-user
When enabled, creates Demo project and quick start guide for inital user (default:
true
)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.tipOnce 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.
tipTolgee 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.
dangerWhen 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. When SSO is enabled, users can still register via SSO, even if this setting is set tofalse
. (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 tofalse
. In that case, the user without organization has no permissions on the server.When SSO authentication is enabled, users created by SSO don't have their own organization automatically created no matter the value of this setting. (default:
true
)
GitHub
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:
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. Multiple Google Workspace domains can be separated by a comma
,
. If nothing is set, anyone can log in with their Google account.
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.
Server wide Single Sign-On
Prefix: tolgee.authentication.sso-global
Single sign-on (SSO) is an authentication process that allows a user to access multiple applications with one set of login credentials. To use SSO in Tolgee, can either configure global SSO settings in this section or in refer to sso-organizations
section for enabling the per Organization mode.
There is a significant difference between global and per organization SSO: Global SSO can handle authentication for all server users no matter which organizations they belong to, while per organization SSO can handle authentication only for users of the organization and such users cannot be members of any other organization. SSO users associated with per organization SSO have no rights to create or manage organizations. Global SSO users should be invited to organizations they need to have access to. Per organization SSO users are automatically added to the organization they belong to.
authorization-uri
URL to redirect users for authentication
client-id
Unique identifier for an application
client-secret
Key used to authenticate the application
custom-login-text
Custom text for the SSO login page.
custom-logo-url
Custom logo URL to be displayed on the login screen. Can be set only when
nativeEnabled
isfalse
.domain
Used to identify the organization on login page
enabled
Enables SSO authentication on global level - as a login method for the whole server (default:
false
)session-expiration-minutes
Minutes after which the server will recheck the user's with the SSO provider to ensure the user account is still valid. This is to prevent the user from being able to access the server after the account has been disabled or deleted in the SSO provider. (default:
10
)token-uri
URL for exchanging authorization code for tokens
Per-Organization Single Sign-On
Prefix: tolgee.authentication.sso-organizations
Single sign-on (SSO) is an authentication process that allows a user to access multiple applications with one set of login credentials. To use SSO in Tolgee, can either configure global SSO settings in sso-global
section or in the per Organization mode by setting the enable
to true
in this section and configuring it separately for each organization in the organization settings.
There is a significant difference between global and per organization SSO: Global SSO can handle authentication for all server users no matter which organizations they belong to, while per organization SSO can handle authentication only for users of the organization and such users cannot be members of any other organization. SSO users associated with per organization SSO have no rights to create or manage organizations. Global SSO users should be invited to organizations they need to have access to. Per organization SSO users are automatically added to the organization they belong to.
enabled
Enables SSO authentication (default:
false
)session-expiration-minutes
Minutes after which the server will recheck the user's with the SSO provider to ensure the user account is still valid. This is to prevent the user from being able to access the server after the account has been disabled or deleted in the SSO provider. (default:
10
)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
)
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
)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.
infoIn 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(default:
false
)
Content Delivery
Prefix: tolgee.content-delivery
These properties are used to configure default server content delivery storage.
To get content delivery working, you have to configure the Storage (e.g. S3 or Blob).
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.
cache-purging
Prefix: tolgee.content-delivery.cache-purging
azure-front-door
Prefix: tolgee.content-delivery.cache-purging.azure-front-door
client-id
client-secret
content-root
endpoint-name
profile-name
resource-group-name
subscription-id
tenant-id
cloudflare
Prefix: tolgee.content-delivery.cache-purging.cloudflare
api-key
content-delivery-cache-purging-type
enabled
max-files-per-request
Number of paths to purge in one request. (Cloudflare limit is 30 now, but it might be subject to change) (default:
30
)origins
If cache is filled with specific Origin header, it can be purged only if the purge request specifies the same Origin header. Here you can specify comma separated list of origins. e.g.
https://example.com,https://example2.com
Read more in the Cloudflare docs.
url-prefix
zone-id
storage
Prefix: tolgee.content-delivery.storage
azure
Prefix: tolgee.content-delivery.storage.azure
s3
Prefix: tolgee.content-delivery.storage.s3
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
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
dangerWhile 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.
infoYour 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
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
)
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
)
tolgee
Prefix: tolgee.machine-translation.tolgee
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.
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 thetolgee/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.
dangerIt 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
)email-verification-request-limit
email-verification-request-limit-enabled
email-verification-request-window
enabled
To turn all rate limits off, set this value to
false
.dangerThis field is deprecated and will be removed with Tolgee 4. If set to
false
, it will take priority over the more granularglobal-limits
,endpoint-limits
andauthentication-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)
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.
slack
Prefix: tolgee.slack
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.
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
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-demo-for-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:
oauth2:
authorization-url:
client-id:
client-secret:
scopes: []
token-url:
user-url:
sso-global:
authorization-uri:
client-id:
client-secret:
custom-login-text:
custom-logo-url:
domain:
enabled: false
session-expiration-minutes: 10
token-uri:
sso-organizations:
enabled: false
session-expiration-minutes: 10
batch:
concurrency: 1
cache:
caffeine-max-size: -1
clean-on-startup: true
default-ttl: 7200000
enabled: false
use-redis: false
content-delivery:
public-url-prefix:
cache-purging:
azure-front-door:
client-id:
client-secret:
content-root:
endpoint-name:
profile-name:
resource-group-name:
subscription-id:
tenant-id:
cloudflare:
api-key:
content-delivery-cache-purging-type: CLOUDFLARE
enabled: false
max-files-per-request: 30
origins:
url-prefix:
zone-id:
storage:
azure:
connection-string:
container-name:
s3:
access-key:
bucket-name:
endpoint:
secret-key:
signing-region:
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:
store-files-for-debugging: false
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
google:
api-key:
default-enabled: true
default-primary: true
tolgee:
default-enabled: true
default-primary: true
postgres-autostart:
container-name: tolgee_postgres
database-name: postgres
enabled: true
max-wait-time: 300
mode: DOCKER
password: postgres
port: 25432
stop: true
user: postgres
rate-limit:
authentication-limits: true
email-verification-request-limit: 2
email-verification-request-limit-enabled: true
email-verification-request-window: 60000
enabled: true
endpoint-limits: true
global-limits: true
ip-request-limit: 20000
ip-request-window: 300000
user-request-limit: 400
user-request-window: 60000
recaptcha:
secret-key:
site-key:
sentry:
client-dsn:
server-dsn:
traces-sample-rate:
slack:
client-id:
client-secret:
signing-secret:
token:
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