Running with Docker

info

Since v2, Tolgee runs PostgreSQL database in its container by default. To disable embedded Postgres, set tolgee.postgres-autostart.enabled property to false. Then you can use an external database with the smaller slim image that omits the embedded PostgreSQL server.

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:25432' # 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:25432'
      - '8080:8080'
    env_file:
      - .env

To provide a configuration, add following .env file.

.env

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.

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

For some users, running the PostgreSQL database in a separate container is beneficial. Here is how you can do it.

Since this setup brings its own database, it is the ideal place to use the slim image tolgee/tolgee:slim. The slim image is the same application on a smaller JRE-only base without the embedded PostgreSQL server, so it doesn't carry PostgreSQL binaries you would never run here. It already ships with postgres autostart disabled, so always pair it with an external database like the one below.

Tag	Description
tolgee/tolgee:slim	Latest slim build
tolgee/tolgee:<version>-slim	Slim image for a specific release, for example tolgee/tolgee:v3.0.0-slim

Create a docker-compose.yaml that runs the slim image next to a dedicated PostgreSQL container.

services:
  app:
    image: tolgee/tolgee:slim
    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:15
    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 15 container. Now, you have to modify the Tolgee configuration to use this database.

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.

note

If you prefer the default tolgee/tolgee image here, it bundles PostgreSQL as well, so you must also disable the embedded server by adding tolgee.postgres-autostart.enabled: false to config.yaml.

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

note

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.