From 76d7c9bd6952926e5037b93b2ab08c7a4ce02b6b Mon Sep 17 00:00:00 2001 From: Daniel Krizan Date: Fri, 17 Jul 2026 12:12:49 +0200 Subject: [PATCH 1/2] ci: run docs codegen against external postgres 17 The EE image is becoming slim and bundles no postgres server, so the job needs a database of its own. Postgres 13 went end of life in November 2025. --- .github/workflows/update-generated-code.yaml | 20 +++++++++++++++++++- 1 file changed, 19 insertions(+), 1 deletion(-) diff --git a/.github/workflows/update-generated-code.yaml b/.github/workflows/update-generated-code.yaml index c41aefbdd..d67832324 100644 --- a/.github/workflows/update-generated-code.yaml +++ b/.github/workflows/update-generated-code.yaml @@ -10,6 +10,19 @@ jobs: main: name: Update docs runs-on: ubuntu-latest + services: + postgres: + image: postgres:17 + env: + POSTGRES_PASSWORD: postgres + POSTGRES_DB: postgres + ports: + - 5432:5432 + options: >- + --health-cmd pg_isready + --health-interval 5s + --health-timeout 3s + --health-retries 10 steps: - uses: actions/checkout@v6 with: @@ -34,7 +47,12 @@ jobs: - name: Run the app & wait run: | - docker run --rm -d -p 8080:8080 -e tolgee.billing.createPlansOnStartup=true ghcr.io/tolgee/tolgee-ee:${{ github.event.inputs.version }} + docker run --rm -d --network host \ + -e tolgee.billing.createPlansOnStartup=true \ + -e SPRING_DATASOURCE_URL=jdbc:postgresql://localhost:5432/postgres \ + -e SPRING_DATASOURCE_USERNAME=postgres \ + -e SPRING_DATASOURCE_PASSWORD=postgres \ + ghcr.io/tolgee/tolgee-ee:${{ github.event.inputs.version }} curl --retry 200 --retry-delay 1 -s --retry-all-errors "http://localhost:8080/swagger-ui/index.html" > /dev/null - name: Generate the code From 58f74765af72fae09f808ac4ef5090b050d01811 Mon Sep 17 00:00:00 2001 From: Daniel Krizan Date: Fri, 17 Jul 2026 12:12:49 +0200 Subject: [PATCH 2/2] docs: warn that v4 removes the bundled postgres and document the migration The bundled server is PostgreSQL 13, end of life since November 2025, so the migration leads with a dump into PostgreSQL 17 and keeps reusing the existing files on 13 as the quicker alternative. The external database example sets up an empty database, which is the wrong thing to copy for a migration: a newer PostgreSQL refuses to start on the files the bundled server leaves behind. --- platform/self_hosting/running_with_docker.mdx | 187 +++++++++++++++++- 1 file changed, 180 insertions(+), 7 deletions(-) diff --git a/platform/self_hosting/running_with_docker.mdx b/platform/self_hosting/running_with_docker.mdx index 62f5cac19..431595b13 100644 --- a/platform/self_hosting/running_with_docker.mdx +++ b/platform/self_hosting/running_with_docker.mdx @@ -6,10 +6,15 @@ slug: /self_hosting/running_with_docker image: /img/og-images/self-hosting.png --- -:::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 external database as -[described below](/platform/self_hosting/running_with_docker#running-with-docker-compose-with-external-postgresql-database). +:::caution +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](/platform/self_hosting/running_with_docker#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) @@ -88,6 +93,11 @@ cat data/initial.pwd For simple local development or testing, you can run Tolgee in a single container with embedded PostgreSQL database. +:::caution +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{{dockerTagVersion}} ``` @@ -101,7 +111,9 @@ This will: Now you should be able to access Tolgee web application on [http://localhost:8085](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. + +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. ```yaml title=docker-compose.yaml services: @@ -120,7 +132,7 @@ services: depends_on: - db db: - image: postgres:15 + image: postgres:17 environment: POSTGRES_DB: postgres POSTGRES_USER: postgres @@ -131,7 +143,7 @@ services: - '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. +This configuration creates a separate Postgres 17 container. Now, you have to modify the Tolgee configuration to use this database. ```yaml title=config.yaml tolgee: @@ -146,6 +158,167 @@ spring: Don't forget to change the `POSTGRES_USER`, `POSTGRES_PASSWORD`, `username` and `password` properties to your values. +:::note +This example sets up a new, empty database. If you already have data in the bundled PostgreSQL, follow +[migrate from the bundled database](#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. + +:::caution +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. +::: + +### Move 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`. + +```yaml title=docker-compose.yaml +services: + app: + image: tolgee/tolgee{{dockerTagVersion}} + 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. + +```yaml title=config.yaml +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. + +### Keep 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. + +:::caution +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. + +```yaml title=docker-compose.yaml +services: + app: + image: tolgee/tolgee{{dockerTagVersion}} + 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. + +```yaml title=config.yaml +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](/platform/translation_process/qa_checks) include Spelling and Grammar checks powered by [LanguageTool](https://languagetool.org/). These checks require a separate LanguageTool container.