feat: well designed transactional e-mails

.github/actions/download-backend-build/action.yaml

@@ -1,6 +1,11 @@
 name: Download backend build
 description: Download backend build from GitHub artifacts and decompress them
 
+inputs:
+  base-directory:
+    description: Base directory for the backend build. Defaults to current working directory.
+    default: .
+
 runs:
   using: composite
   steps:
@@ -10,16 +15,19 @@ runs:
         name: backend
         path: ~/
 
-    - name: Un-tar build results
-      shell: sh
+    - name: Decompress build results
+      shell: bash
+      env:
+        BASE_DIR: ${{ inputs.base-directory }}
       run: |
-        tar --zstd -xf ~/backend-api.tar.zst ./backend/api/build
-        tar --zstd -xf ~/backend-app.tar.zst ./backend/app/build
-        tar --zstd -xf ~/backend-data.tar.zst ./backend/data/build
-        tar --zstd -xf ~/backend-misc.tar.zst ./backend/misc/build
-        tar --zstd -xf ~/backend-security.tar.zst ./backend/security/build
-        tar --zstd -xf ~/backend-testing.tar.zst ./backend/testing/build
-        tar --zstd -xf ~/backend-ktlint.tar.zst ./backend/ktlint/build
-        tar --zstd -xf ~/backend-development.tar.zst ./backend/development/build
-        tar --zstd -xf ~/ee-backend-app.tar.zst ./ee/backend/app/build
-        tar --zstd -xf ~/ee-backend-tests.tar.zst ./ee/backend/tests/build
+        tar --zstd -xf ~/backend-api.tar.zst $BASE_DIR/backend/api/build
+        tar --zstd -xf ~/backend-app.tar.zst $BASE_DIR/backend/app/build
+        tar --zstd -xf ~/backend-data.tar.zst $BASE_DIR/backend/data/build
+        tar --zstd -xf ~/backend-misc.tar.zst $BASE_DIR/backend/misc/build
+        tar --zstd -xf ~/backend-security.tar.zst $BASE_DIR/backend/security/build
+        tar --zstd -xf ~/backend-testing.tar.zst $BASE_DIR/backend/testing/build
+        tar --zstd -xf ~/backend-ktlint.tar.zst $BASE_DIR/backend/ktlint/build
+        tar --zstd -xf ~/backend-development.tar.zst $BASE_DIR/backend/development/build
+        tar --zstd -xf ~/ee-backend-app.tar.zst $BASE_DIR/ee/backend/app/build
+        tar --zstd -xf ~/ee-backend-tests.tar.zst $BASE_DIR/ee/backend/tests/build
+        tar --zstd -xf ~/backend-email.tar.zst $BASE_DIR/email/out

.github/actions/setup-env/action.yaml

@@ -9,8 +9,21 @@ inputs:
     description: Whether to setup Node.js or not.
     default: "true"
   npm-cache:
-    description: Whether to setup npm cache or not.
+    description: Whether to setup npm cache or not. Irrelevant if node is disabled.
     default: "true"
+  docker:
+    description: Whether to setup additional Docker build environment tools. Defaults to false.
+    default: "false"
+  docker-ghcr:
+    description: Whether to login to the GitHub Container Registry or not. Defaults to false.
+    default: "false"
+  docker-hub:
+    description: Whether to login to Docker Hub or not. Defaults to false.
+    default: "false"
+  docker-hub-username:
+    description: Username to use to authenticate to Docker Hub.
+  docker-hub-password:
+    description: Password to use to authenticate to Docker Hub.
 
 runs:
   using: composite
@@ -40,3 +53,26 @@ runs:
         key: cache-node-modules-${{ runner.os }}-${{ hashFiles('**/package-lock.json') }}
         restore-keys: |
           cache-node-modules-${{ runner.os }}-
+
+    - name: Setup QEMU for Docker
+      if: "${{ inputs.docker == 'true' }}"
+      uses: docker/setup-qemu-action@v3
+
+    - name: Setup Docker Buildx
+      if: "${{ inputs.docker == 'true' }}"
+      uses: docker/setup-buildx-action@v3
+
+    - name: Login to Docker Hub
+      if: "${{ inputs.docker-hub == 'true' }}"
+      uses: docker/login-action@v3
+      with:
+        username: ${{ inputs.docker-hub-username }}
+        password: ${{ inputs.docker-hub-password }}
+
+    - name: Login to GitHub Container Registry
+      if: "${{ inputs.docker-ghcr == 'true' }}"
+      uses: docker/login-action@v3
+      with:
+        registry: ghcr.io
+        username: ${{ github.actor }}
+        password: ${{ github.token }}

.github/actions/upload-backend-build/action.yaml

@@ -1,24 +1,33 @@
 name: Upload backend build
 description: Compress and upload backend build result to GitHub artifacts
 
+inputs:
+  base-directory:
+    description: Base directory for the backend build. Defaults to current working directory.
+    default: .
+
 runs:
   using: composite
   steps:
-    - name: Compress build assets
-      shell: sh
+    - name: Compress build results
+      shell: bash
+      env:
+        BASE_DIR: ${{ inputs.base-directory }}
       run: |
-        tar --zstd -cf ~/backend-api.tar.zst ./backend/api/build
-        tar --zstd -cf ~/backend-app.tar.zst ./backend/app/build
-        tar --zstd -cf ~/backend-data.tar.zst ./backend/data/build
-        tar --zstd -cf ~/backend-misc.tar.zst ./backend/misc/build
-        tar --zstd -cf ~/backend-security.tar.zst ./backend/security/build
-        tar --zstd -cf ~/backend-testing.tar.zst ./backend/testing/build
-        tar --zstd -cf ~/backend-ktlint.tar.zst ./backend/ktlint/build
-        tar --zstd -cf ~/backend-development.tar.zst ./backend/development/build
-        tar --zstd -cf ~/ee-backend-app.tar.zst ./ee/backend/app/build
-        tar --zstd -cf ~/ee-backend-tests.tar.zst ./ee/backend/tests/build
+        tar --zstd -cf ~/backend-api.tar.zst $BASE_DIR/backend/api/build
+        tar --zstd -cf ~/backend-app.tar.zst $BASE_DIR/backend/app/build
+        tar --zstd -cf ~/backend-data.tar.zst $BASE_DIR/backend/data/build
+        tar --zstd -cf ~/backend-misc.tar.zst $BASE_DIR/backend/misc/build
+        tar --zstd -cf ~/backend-security.tar.zst $BASE_DIR/backend/security/build
+        tar --zstd -cf ~/backend-testing.tar.zst $BASE_DIR/backend/testing/build
+        tar --zstd -cf ~/backend-ktlint.tar.zst $BASE_DIR/backend/ktlint/build
+        tar --zstd -cf ~/backend-development.tar.zst $BASE_DIR/backend/development/build
+        tar --zstd -cf ~/ee-backend-app.tar.zst $BASE_DIR/ee/backend/app/build
+        tar --zstd -cf ~/ee-backend-tests.tar.zst $BASE_DIR/ee/backend/tests/build
+        tar --zstd -cf ~/backend-email.tar.zst $BASE_DIR/email/out
 
-    - uses: actions/upload-artifact@v4
+    - name: Upload backend build result
+      uses: actions/upload-artifact@v4
       with:
         name: backend
         path: |
@@ -32,3 +41,4 @@ runs:
           ~/backend-development.tar.zst
           ~/ee-backend-app.tar.zst
           ~/ee-backend-tests.tar.zst
+          ~/backend-email.tar.zst

.github/workflows/prerelease-alpha.yml

@@ -50,16 +50,21 @@ jobs:
         if: ${{ steps.version.outputs.VERSION != '' }}
         run: docker login -u ${{ secrets.DOCKERHUB_USERNAME }} -p "${{ secrets.DOCKERHUB_PASSWORD }}"
 
-      - name: Create docker image
+      - name: Prepare for docker build
         if: ${{ steps.version.outputs.VERSION != '' }}
-        run: |
-          docker buildx create --use
-          ./gradlew dockerPublish
+        run: ./gradlew dockerPrepare
         env:
           VERSION: ${{ steps.version.outputs.VERSION }}
           TOLGEE_API_KEY: ${{secrets.TOLGEE_API_KEY}}
           TOLGEE_API_URL: ${{secrets.TOLGEE_API_URL}}
 
+      - name: Create docker image
+        if: ${{ steps.version.outputs.VERSION != '' }}
+        run: |
+          docker buildx create --use
+          docker buildx build . -t tolgee/tolgee:${{ steps.version.outputs.VERSION }} --platform linux/arm64,linux/amd64 --push
+        working-directory: build/docker
+
       - name: Pack with webapp
         if: ${{ steps.version.outputs.VERSION != '' }}
         run: ./gradlew packResources

.github/workflows/preview.yml

@@ -42,16 +42,18 @@ jobs:
         id: version
         run: echo "VERSION=$(echo $GITHUB_REF | sed -e 's/refs\/tags\///g' -e 's/\//-/g')" >> $GITHUB_OUTPUT
 
-      - name: Create docker image
-        run: |
-          docker buildx create --use
-          ./gradlew dockerPublish
+      - name: Prepare for docker build
+        run: ./gradlew dockerPrepare
         env:
-          VERSION: ${{ steps.version.outputs.VERSION }}
-          DOCKER_IMAGE: tgint/tgpreview
           TOLGEE_API_KEY: ${{secrets.TOLGEE_API_KEY}}
           TOLGEE_API_URL: ${{secrets.TOLGEE_API_URL}}
 
+      - name: Create docker image
+        run: |
+          docker buildx create --use 
+          docker buildx build . -t tgint/tgpreview:${{ steps.version.outputs.VERSION }} --platform linux/arm64,linux/amd64 --push
+        working-directory: build/docker
+
       - name: Deploy
         uses: nickgronow/kubectl@master
         with:

.github/workflows/reportIntermittentTests.yml

@@ -58,6 +58,7 @@ jobs:
           ./gradlew ${{ matrix.command.run }};
         env:
           SKIP_SERVER_BUILD: true
+          SKIP_EMAIL_BUILD: true
 
       - name: Get report name
         id: reportName
@@ -135,6 +136,7 @@ jobs:
           TOLGEE_API_URL: ${{secrets.TOLGEE_API_URL}}
           SKIP_WEBAPP_BUILD: true
           SKIP_SERVER_BUILD: true
+          SKIP_EMAIL_BUILD: true
           SKIP_INSTALL_E2E_DEPS: true
           E2E_TOTAL_JOBS: ${{matrix.total_jobs}}
           E2E_JOB_INDEX: ${{matrix.job_index}}

.github/workflows/test.yml

@@ -18,12 +18,13 @@ jobs:
 
       # Don't build test classes here; they'll only be used once during the test run anyway.
       # This amortizes the cost of compilation across each test job, rather than paying it upfront.
+      # Test emails are built nonetheless, as they may be used by multiple subprojects...
       #
       # Note: seems like running in parallel has the weird side effect of causing Spring dependency management to hang
       # It's very occasional, and doesn't seem to occur locally, but parallel being the issue is possible
       # See: https://github.com/spring-gradle-plugins/dependency-management-plugin/issues/370
       - name: Build backend
-        run: ./gradlew classes jar bootJar
+        run: ./gradlew classes jar bootJar buildTestEmails
 
       - name: Upload backend build result
         uses: ./.github/actions/upload-backend-build
@@ -71,6 +72,7 @@ jobs:
           command: ./gradlew ${{ matrix.command }}
         env:
           SKIP_SERVER_BUILD: true
+          SKIP_EMAIL_BUILD: true
           CI_RELEASE: ${{ github.event_name == 'push' && true || false }}
 
       - name: Get report name
@@ -176,6 +178,7 @@ jobs:
           TOLGEE_API_URL: ${{secrets.TOLGEE_API_URL}}
           SKIP_WEBAPP_BUILD: true
           SKIP_SERVER_BUILD: true
+          SKIP_EMAIL_BUILD: true
           SKIP_INSTALL_E2E_DEPS: true
           E2E_TOTAL_JOBS: ${{matrix.total_jobs}}
           E2E_JOB_INDEX: ${{matrix.job_index}}
@@ -297,7 +300,7 @@ jobs:
         run: |
           ./gradlew server-app:bootRun --args='--spring.profiles.active=dev' &
           echo "Waiting for backend to start..."
-          timeout 120 bash -c 'until curl -s http://localhost:8080/actuator/health > /dev/null 2>&1; do sleep 2; done'
+          timeout 180 bash -c 'until curl -s http://localhost:8080/actuator/health > /dev/null 2>&1; do sleep 2; done'
           echo "Backend is ready"
         env:
           SKIP_SERVER_BUILD: true
@@ -454,12 +457,36 @@ jobs:
       - name: Run ktlint
         run: ./gradlew ktlintCheck
 
+  email-code-checks:
+    name: Email templates static check 🪲
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup environment
+        uses: ./.github/actions/setup-env
+        with:
+          java: 'false'
+
+      - name: Install dependencies
+        run: npm ci
+        working-directory: ./email
+
+      - name: TypeScript
+        run: npm run tsc
+        working-directory: ./email
+
+      - name: ESLint
+        run: npm run eslint
+        working-directory: ./email
+
   everything-passed:
     name: Everything passed 🎉
     needs:
       - backend-build
       - backend-test
       - backend-code-checks
+      - email-code-checks
       - frontend-build
       - frontend-code-check
       - schema-check
@@ -519,6 +546,10 @@ jobs:
             failed_jobs+=("e2e-install-deps")
           fi
 
+          if [[ "${{ needs.email-code-checks.result }}" != "success" ]]; then
+            failed_jobs+=("email-code-checks")
+          fi
+
           if [[ "${#failed_jobs[@]}" -gt 0 ]]; then
             echo "The following jobs failed: ${failed_jobs[*]}"
             exit 1

DEVELOPMENT.md

@@ -73,6 +73,10 @@ To learn more about externalized configuration in Spring boot, read [the docs](h
 
 Since we set the active profile to `dev`, Spring uses the `application-dev.yaml` configuration file.
 
+## Writing emails
+
+Please refer to [email/HACKING.md](email/HACKING.md).
+
 ## Updating the database changelog
 
 Tolgee uses Liquibase to handle the database migration. The migrations are run on every app startup. To update the changelog, run:

backend/api/build.gradle

@@ -25,10 +25,6 @@ apply plugin: "org.jetbrains.kotlin.plugin.spring"
 apply plugin: "kotlin-allopen"
 apply plugin: 'io.spring.dependency-management'
 
-repositories {
-    mavenCentral()
-}
-
 java {
     toolchain {
         languageVersion = JavaLanguageVersion.of(21)
@@ -102,6 +98,6 @@ dependencyManagement {
     }
 }
 
-jar {
+tasks.named('jar', Jar) {
     duplicatesStrategy(DuplicatesStrategy.EXCLUDE)
 }

backend/api/src/main/kotlin/io/tolgee/controllers/resetPassword/ResetPasswordRequestHandler.kt

@@ -47,15 +47,12 @@ class ResetPasswordRequestHandler(
       EmailParams(
         to = request.email,
         subject = if (isInitial) "Initial password configuration" else "Password reset",
+        header = "Password reset",
         text =
           """
-          Hello! 👋<br/><br/>
           ${if (isInitial) "To set a password for your account, <b>follow this link</b>:<br/>" else "To reset your password, <b>follow this link</b>:<br/>"}
           <a href="$url">$url</a><br/><br/>
           If you have not requested this e-mail, please ignore it.<br/><br/>
-
-          Regards,<br/>
-          Tolgee
           """.trimIndent(),
       )
 
@@ -67,15 +64,12 @@ class ResetPasswordRequestHandler(
       EmailParams(
         to = request.email,
         subject = "Password reset - SSO managed account",
+        header = "Password reset",
         text =
           """
-          Hello! 👋<br/><br/>
           We received a request to reset the password for your account. However, your account is managed by your organization and uses a single sign-on (SSO) service to log in.<br/><br/>
           To access your account, please use the "SSO Login" button on the Tolgee login page. No password reset is needed.<br/><br/>
           If you did not make this request, you may safely ignore this email.<br/><br/>
-
-          Regards,<br/>
-          Tolgee
           """.trimIndent(),
       )