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.
-
portPort 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.
-
urlThe url of the datasource in format
jdbc:postgresql://host:port/dbname. e.g.jdbc:postgresql://db:5432/postgres -
usernameDatabase username. e.g.
postgres -
passwordDatabase password. e.g.
postgres
Tolgee
Prefix: tolgee
Configuration specific to Tolgee.
-
file-storage-urlPublic base path where files are accessible. Used by the user interface.
-
front-end-urlPublic URL where Tolgee is accessible. Used to generate links to Tolgee (e.g. email confirmation link).
Warning: Not providing this property leads to security issues.Providing this property is highly recommended especially if you are managing publicly accessible Tolgee instance.
-
max-screenshots-per-keyMaximum amount of screenshots which can be uploaded per API key. (default:
20) -
max-translation-text-lengthMaximum length of translations. (default:
10000) -
max-upload-file-sizeMaximum size of uploaded files (in kilobytes). (default:
51200≈ 50MB) -
translations-view-languages-limitMaximum amount of languages that can be selected in the Translations view (default:
10)
Authentication
Prefix: tolgee.authentication
Configuration of Tolgee's authentication.
-
create-demo-for-initial-userWhen enabled, creates Demo project and quick start guide for inital user (default:
true) -
enabledWhether 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:
truewhen running with Java directly,falsewhen running via Docker.) -
initial-passwordPassword of initial user. If unspecified, a random password will be generated and stored in the
initial.pwdfile, 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-usernameUsername 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-expirationExpiration time of generated JWT tokens in milliseconds. (default:
604800000= 7 days) -
jwt-secretSecret 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.
warningWhen running multiple replicas, it is required to set it, or you will be constantly logged out otherwise.
-
jwt-super-expirationExpiration time of generated JWT tokens for superuser in milliseconds. (default:
3600000= 1 hour) -
native-enabledWhether 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-verificationWhether users need to verify their email addresses when creating their account. Requires a valid SMTP configuration. (default:
false) -
registrations-allowedWhether 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-retrievalWhether 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-ageExpiration time of a generated image access token in milliseconds. (default:
7200000= 2 hours) -
user-can-create-organizationsWhether 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) -
create-initial-userRemoved 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.
-
user-can-create-projectsRemoved in: 2.33.0
Whether regular users are allowed to create projects. When disabled, only administrators can create projects (default:
true)
GitHub
Prefix: tolgee.authentication.github
GitHub authentication can be used in combination with native authentication.
-
authorization-urlURL 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-idOAuth Client ID, obtained in GitHub administration.
-
client-secretOAuth Client secret, obtained in GitHub administration.
-
user-urlURL to GitHub's
/userAPI 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-urlURL to Google
/tokenAPI endpoint. This usually does not need to be changed. (default:https://oauth2.googleapis.com/token) -
client-idOAuth Client ID, obtained in Google Cloud Console.
-
client-secretOAuth Client secret, obtained in Google Cloud Console.
-
user-urlURL to Google
/userinfoAPI endpoint. This usually does not need to be changed. (default:https://www.googleapis.com/oauth2/v3/userinfo) -
workspace-domainThe 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-urlURL to OAuth2 authorize API endpoint. This endpoint will exposed to the frontend.
-
client-idOAuth2 Client ID
-
client-secretOAuth2 Client secret
-
scopesOauth2 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 profileis used for this. (But can also be different depending on the provider) (default:[]) -
token-urlURL to OAuth2 token API endpoint.
-
user-urlURL 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-uriURL to redirect users for authentication
-
client-idUnique identifier for an application
-
client-secretKey used to authenticate the application
-
custom-login-textCustom text for the SSO login page.
-
custom-logo-urlCustom logo URL to be displayed on the login screen. Can be set only when
nativeEnabledisfalse. -
domainUsed to identify the organization on login page
-
enabledEnables SSO authentication on global level - as a login method for the whole server (default:
false) -
forceWhen true, users with an email matching the organization's domain must sign in using SSO (default:
false) -
session-expiration-minutesMinutes 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-uriURL 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.
-
enabledEnables SSO authentication (default:
false) -
session-expiration-minutesMinutes 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)
Batch operations
Prefix: tolgee.batch
Configuration of batch operations.
-
concurrencyHow 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-sizeMaximum 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-startupWhether to clean the cache on Tolgee startup (default:
true) -
default-ttlTTL of cache data, in milliseconds. (default:
7200000≈ 2 hours) -
enabledWhether Tolgee should use a cache. (default:
false) -
use-redisWhether 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-prefixThe prefix URL where the content is accessible from the public. If this property is not null, content delivery will be enabled on your server.
For example, if you set this property to
https://cdn.example.com/
Cache purging
Prefix: tolgee.content-delivery.cache-purging
Several services can be used as cache. Tolgee is able to purge the cache when new files are published when this configuration is set.
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