Running with Docker
Tolgee runs a PostgreSQL database in its container by default, and Tolgee v4 removes it from the tolgee/tolgee
image. Every setup that relies on the bundled database has to move to an external PostgreSQL database before
upgrading to v4.
You can make this move today, on your current version, by following migrate from the bundled database. It keeps your data where it is, so it needs no dump and restore. Once your data lives in an external database, upgrading to v4 needs no further changes.
Running with Docker Compose (recommended)
The recommended way to run Tolgee is using Docker Compose with a configuration YAML file. This approach provides better configuration management and is more suitable for production environments.
To start, create and enter a folder to store Tolgee related files:
mkdir tolgee && cd tolgee
Create a config.yaml file containing your configuration properties. You can find the list of all properties in configuration reference.
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
Create a file named docker-compose.yml containing the following content:
services:
app:
image: tolgee/tolgee
volumes:
- ./data:/data
- ./config.yaml:/config.yaml
ports:
- '25432:5432' # if you would like to access the DB
- '8080:8080'
environment:
spring.config.additional-location: file:///config.yaml
Now you can start Tolgee by running:
docker-compose up -d
You should be able to access Tolgee web application on http://localhost:8080
Alternative: Configuring using environmental variables
Alternatively, you can provide the configuration variables using environment variables or using .env file instead of the YAML configuration file.
services:
app:
image: tolgee/tolgee
volumes:
- ./data:/data
ports:
- '25432:5432'
- '8080:8080'
env_file:
- .env
To provide a configuration, add following .env file.
TOLGEE_AUTHENTICATION_ENABLED=true
TOLGEE_AUTHENTICATION_INITIAL_PASSWORD=admin
TOLGEE_AUTHENTICATION_INITIAL_USERNAME=admin
TOLGEE_AUTHENTICATION_JWT_SECRET=my_jwt_secret
TOLGEE_MACHINE_TRANSLATION_GOOGLE_API_KEY=my_google_api_key
TOLGEE_SMTP_AUTH=true
TOLGEE_SMTP_FROM=Tolgee <no-reply@mydomain.com>
TOLGEE_SMTP_HOST=email-smtp.regional-region.amazonaws.com
TOLGEE_SMTP_PASSWORD=omg/my/password
TOLGEE_SMTP_PORT=465
TOLGEE_SMTP_SSL_ENABLED=true
TOLGEE_SMTP_USERNAME=user@company.com
Similarly, you can define other configuration properties.
Your initial username is admin. Initial password is automatically generated and stored in /data/initial.pwd file in the
Tolgee container. You can print it by executing this:
cat data/initial.pwd
Running Tolgee in single container (alternative)
For simple local development or testing, you can run Tolgee in a single container with embedded PostgreSQL database.
This setup depends on the bundled PostgreSQL database, so it will stop working in Tolgee v4. Don't use it for data you want to keep.
docker run -v tolgee_data:/data/ -p 8085:8080 tolgee/tolgee
This will:
- mount tolgee_data volume into it's directory inside the container
- expose tolgee container port on port 8085
- run the image!
Now you should be able to access Tolgee web application on http://localhost:8085
Running with docker compose with external PostgreSQL database
Running the PostgreSQL database in a separate container gives you full control over your data, and it keeps backups, upgrades and monitoring independent of Tolgee itself. Here is how you can do it.
services:
app:
image: tolgee/tolgee:latest
volumes:
- ./data:/data
- ./config.yaml:/config.yaml
ports:
- '8089:8080'
environment:
spring.config.additional-location: file:///config.yaml # <--- this line
deploy:
restart_policy:
condition: on-failure
depends_on:
- db
db:
image: postgres:17
environment:
POSTGRES_DB: postgres
POSTGRES_USER: postgres
POSTGRES_PASSWORD: postgres
volumes:
- ./data/postgres:/var/lib/postgresql/data
ports:
- '25432:5432' # <-- If you want to access your postgres from outside of docker network
This configuration creates a separate Postgres 17 container. Now, you have to modify the Tolgee configuration to use this database.
tolgee:
postgres-autostart:
enabled: false
spring:
datasource:
url: jdbc:postgresql://db:5432/postgres
username: postgres
password: postgres
Don't forget to change the POSTGRES_USER, POSTGRES_PASSWORD, username and password properties to your values.
This example sets up a new, empty database. If you already have data in the bundled PostgreSQL, follow migrate from the bundled database instead. PostgreSQL 17 cannot read the files the bundled server left behind.
Migrate from the bundled database
If you run Tolgee with the bundled PostgreSQL, your data has to move to an external database before you can upgrade to v4. The bundled server is PostgreSQL 13, which reached its end of life in November 2025 and no longer receives security fixes.
There are two ways to do this. Moving to PostgreSQL 17 leaves you on a database that is supported until 2029, and it is the one to pick unless you have a reason not to. Reusing the existing files is quicker and needs no dump, but it keeps you on PostgreSQL 13.
Whichever you pick, keep the ./data:/data mount on the app. Tolgee keeps your file storage and the generated admin
password there. If you drop the mount and your admin has never changed their password, Tolgee generates a new
password on the next start and resets the admin account to it.
Moving to PostgreSQL 17
Dump the bundled database while Tolgee is still running. The bundled image ships the PostgreSQL client tools, so
pg_dump is available inside the container.
docker compose exec -T app pg_dump -U postgres -d postgres > tolgee-dump.sql
Then stop Tolgee.
docker compose down
Add a db service on PostgreSQL 17. Give it a directory of its own, so it doesn't collide with the files the bundled
server left behind in data/postgres.
services:
app:
image: tolgee/tolgee
volumes:
- ./data:/data
- ./config.yaml:/config.yaml
ports:
- '8080:8080'
environment:
spring.config.additional-location: file:///config.yaml
depends_on:
- db
db:
image: postgres:17
environment:
POSTGRES_DB: postgres
POSTGRES_USER: postgres
POSTGRES_PASSWORD: postgres
volumes:
- ./data/postgres17:/var/lib/postgresql/data
Start the database on its own and load the dump into it.
docker compose up -d db
docker compose exec -T db psql -U postgres -d postgres < tolgee-dump.sql
Then tell Tolgee to stop starting a database of its own and to use the new one.
tolgee:
postgres-autostart:
enabled: false
spring:
datasource:
url: jdbc:postgresql://db:5432/postgres
username: postgres
password: postgres
Start everything again.
docker compose up -d
Your projects, translations and users are all still there, and your existing passwords keep working. Once you have
checked everything is in place, you can delete the old data/postgres directory.
Keeping the existing files on PostgreSQL 13
If you would rather not dump and restore, you can hand the bundled server's files straight to a PostgreSQL container.
The bundled server keeps them in data/postgres, which is exactly where a separate PostgreSQL container looks for
them, so the data stays where it is.
The container has to be postgres:13. A newer PostgreSQL refuses to start on PostgreSQL 13 files and fails with
database files are incompatible with server. This leaves you on an end of life database, so treat it as a step on
the way to a supported version rather than a destination.
Stop Tolgee first, so the bundled server shuts down cleanly and leaves its files consistent.
docker compose down
Add a db service pointed at the directory the bundled server already uses.
services:
app:
image: tolgee/tolgee
volumes:
- ./data:/data
- ./config.yaml:/config.yaml
ports:
- '8080:8080'
environment:
spring.config.additional-location: file:///config.yaml
depends_on:
- db
db:
image: postgres:13
environment:
POSTGRES_DB: postgres
POSTGRES_USER: postgres
POSTGRES_PASSWORD: postgres
volumes:
- ./data/postgres:/var/lib/postgresql/data
Because the data directory already exists, the POSTGRES_* variables don't create or change anything, and the users
inside your database stay as they are. What matters is that the datasource credentials match what the bundled server
used. Unless you changed tolgee.postgres-autostart.user or tolgee.postgres-autostart.password, both are
postgres.
Then tell Tolgee to stop starting a database of its own and to use the new one.
tolgee:
postgres-autostart:
enabled: false
spring:
datasource:
url: jdbc:postgresql://db:5432/postgres
username: postgres
password: postgres
Start everything again.
docker compose up -d
Your projects, translations and users are all still there, and your existing passwords keep working.
Optional: Spelling & Grammar checks (LanguageTool)
Tolgee's QA Checks include Spelling and Grammar checks powered by LanguageTool. These checks require a separate LanguageTool container.
Add the LanguageTool service to your docker-compose.yml:
services:
app:
image: tolgee/tolgee
volumes:
- ./data:/data
- ./config.yaml:/config.yaml
ports:
- '8080:8080'
environment:
spring.config.additional-location: file:///config.yaml
depends_on:
- languagetool
languagetool:
image: erikvl87/languagetool:6.7
environment:
- Java_Xms=256m
- Java_Xmx=1024m
Then add the LanguageTool URL to your config.yaml:
tolgee:
language-tool:
url: http://languagetool:8010
Or as an environment variable: TOLGEE_LANGUAGE__TOOL_URL=http://languagetool:8010
Once configured, you can enable Spelling and Grammar checks in your project's QA settings (they default to Off).
The container loads all language models on startup, which can take a while and uses ~1-1.5 GB of memory. Adjust Java_Xmx based on your available resources.