Table of Contents

• YJDH services
  • About YJDH
  • Service environments (Kesäseteli)
  • Requirements
  • Get started
    • Quick start
      • 1. Clone the repository
      • 2. Create all local .env files from the examples
      • 3. Start the stack with Docker
      • 4. Verify backend is running
      • 5. (Optional) Create a Django admin user
      • 6. (Optional) Run the test suites
      • Switching stacks or cleaning up
    • Stack commands
  • Testing
    • Backend tests
    • Frontend tests
  • Local troubleshooting
    • 502 Bad Gateway in frontend
    • Login fails or CORS errors in the browser
    • Access container shell
  • Publishing with Release Please & Git workflow
    • Basics
    • Example workflow
  • Setting up git hooks
  • Kesäseteli employer
    • kesaseteli-employer Development with Docker
  • Kesäseteli youth
    • kesaseteli-youth development with Docker
  • Kesäseteli handler
    • kesaseteli-handler development with Docker
  • Benefit
    • Benefit development with Docker
  • Maintaining and known issues
    • Maintenance tasks (Kesäseteli)
    • Known issues
  • Git blame ignore refs

YJDH services

Yhteisöjen ja järjestöjen digitaalinen Helsinki (= YJDH).

About YJDH

What is it? A monorepo containing code for employment and benefit services used by the City of Helsinki.

Why is it? To provide digital services for managing employment applications and benefits, making it easier for:

• Young people to apply for summer vouchers (Kesäseteli)
• Employers to fulfill employee applications
• City staff to process and handle applications

Who uses the services?

• Youth - Young people (ages 15-18) who apply for summer vouchers through Kesäseteli Youth UI
• Employer - Private or third-sector employers who hire Helsinki residents and submit applications through Kesäseteli Employer UI or Benefit Applicant UI
• Handler - City of Helsinki staff who process and review applications through Handler UIs
• Admin - System administrators who manage configurations and permissions

This monorepo contains code for three different employment services:

• Kesäseteli - Summer voucher system for youth employment

  • Backend
  • Admin
  • Youth UI
  • Employer UI
  • Handler UI

• Benefit / Helsinki-lisä - Discretionary support application system

  • Backend
  • Applicant UI
  • Handler UI

• TET Job Search - retired and can be found in here

  • Backend
  • Youth
  • Admin

Service environments (Kesäseteli)

Service	DEV	TEST	STAGING	PROD
Employer UI	kesaseteli.dev.hel.ninja	yjdh-kesaseteli-ui-test.agw.arodevtest.hel.fi	kesaseteli.stage.hel.ninja	kesaseteli.hel.fi
Youth UI	nuortenkesaseteli.dev.hel.ninja	kesaseteli-youth-ui-test.agw.arodevtest.hel.fi	nuortenkesaseteli.stage.hel.ninja	nuortenkesaseteli.hel.fi
Handler UI	kesaseteli-handler-ui.dev.hel.ninja	kesaseteli-handler-ui-test.agw.arodevtest.hel.fi	kesaseteli-handler-ui.stage.hel.ninja	kesasetelinkasittelija.hel.fi
Backend API & Admin	yjdh-kesaseteli.api.dev.hel.ninja	yjdh-kesaseteli-api-test.agw.arodevtest.hel.fi	kesaseteli-api.stage.hel.ninja	kesaseteli.api.hel.fi

• Deployments: Merge to main triggers dev/test deploys. Merging a Release Please PR creates a version tag that triggers staging deploy. Production requires manual approval in Azure DevOps.
• PR review: Each pull request gets a dynamic review environment and the URL is posted as a comment in the PR.
• Full URLs and details: backend/kesaseteli/docs/kesaseteli-endpoints.md

Requirements

Before starting, ensure you have the following installed:

• Docker@^19.03.0 (or higher)
• Docker Compose@^2.20.0 (or higher)
• NodeJS >=24.18.1
• pnpm@11.18.0
• pre-commit >=4.5.1

Verify your installations:

docker --version
docker compose version
node --version
pnpm --version
pre-commit --version

Ensure Docker Desktop (or the Docker service on Linux) is running before proceeding.

Get started

Quick start

1. Clone the repository

git clone https://github.com/City-of-Helsinki/yjdh.git
cd yjdh

2. Create all local .env files from the examples

Option A: copy manually in file explorer/editor.

Option B: run these commands:

cp .env.kesaseteli-backend.example .env.kesaseteli-backend
cp .env.kesaseteli-employer.example .env.kesaseteli-employer
cp .env.kesaseteli-youth.example .env.kesaseteli-youth
cp .env.kesaseteli-handler.example .env.kesaseteli-handler
cp .env.benefit-backend.example .env.benefit-backend
cp .env.benefit-applicant.example .env.benefit-applicant
cp .env.benefit-handler.example .env.benefit-handler

The example files already contain everything needed to get a development environment up and running. To change or understand individual variables, see Environment variables in the Kesäseteli backend README (and the corresponding example .env files in the repo root).

Note: On Windows Command Prompt, use copy instead of cp.

3. Start the stack with Docker

• Kesäseteli Employer: pnpm employer up
• Kesäseteli Youth/Handler: pnpm youth up or pnpm handler up
• Benefit: pnpm benefit up

Note: On Linux, use the :linux variants (pnpm employer:linux up, pnpm youth:linux up, etc.) for proper file permissions.

Note: Youth and Handler spin up the same stack; don't run both at the same time.

4. Verify backend is running

curl -k https://localhost:8000/admin/

5. (Optional) Create a Django admin user

If you need the admin site (e.g. for handler workflows or debugging):

docker exec -it kesaseteli-backend python manage.py createsuperuser

6. (Optional) Run the test suites

See Testing below.

Switching stacks or cleaning up

To switch stacks or clear issues, run pnpm clean to remove containers and volumes.

Stack commands

Kesäseteli (run only one stack at a time; Youth and Handler share the same stack):

• Employer: pnpm employer up, running at port 3000
• Youth / Handler: pnpm youth up or pnpm handler up, running at ports 3100 and 3200

Benefit (Helsinki-lisä):

• Benefit: pnpm benefit up, Applicant at port 3000 and Handler at 3100

Backend is at https://localhost:8000 in all stacks.

More detail: Kesäseteli employer, youth, handler, Benefit. See also backend and frontend READMEs.

Testing

Backend tests

Backend tests run inside Docker containers using the same setup as development.

From repository root:

Windows:

• Kesäseteli: docker compose -f compose/employer.dev.yml run --rm backend pytest
• Benefit: docker compose -f compose.benefit.yml run --rm backend pytest

Linux (recommended for proper permissions):

• Kesäseteli: UID=$(id -u) GID=$(id -g) docker compose -f compose/employer.dev.yml -f compose/linux.yml run --rm backend pytest
• Benefit: UID=$(id -u) GID=$(id -g) docker compose -f compose.benefit.yml run --rm backend pytest

Note: On Linux, the UID/GID prefix ensures the container runs with your user's UID/GID, preventing permission issues. Add -f compose/linux.yml to the command when using Kesäseteli compose files.

Note: Instead of prefixing every command with UID=$(id -u) GID=$(id -g), you can export them once: in your shell for a session (export UID GID after setting them), with direnv in the project directory, or in .bashrc/.zshrc (or similar).

Frontend tests

Frontend tests run locally (not in Docker) and require Node.js and pnpm.

Prerequisites: Install frontend dependencies first (if not already done). From the repository root run pnpm --dir frontend install, or run pnpm install from the frontend directory.

From repository root:

• Run all frontend tests: pnpm --dir frontend test
• Run Kesäseteli Employer tests only: pnpm --dir frontend ks-empl:test
• Run Kesäseteli Youth tests only: pnpm --dir frontend ks-youth:test
• Run Benefit Handler tests only: pnpm --dir frontend bf-hdlr:test
• Run Benefit Applicant tests only: pnpm --dir frontend bf-appl:test

Note: Frontend tests require local Node.js and pnpm installation.

Local troubleshooting

On Linux: Use the :linux script variants (e.g. pnpm employer:linux up) when starting the stack, and for backend tests use the UID/GID prefix and add -f compose/linux.yml. See Backend tests and Quick start.

502 Bad Gateway in frontend

Usually the backend is not running or has crashed. Check that the backend is up (e.g. curl -k https://localhost:8000/admin/) and check logs:

docker logs -f kesaseteli-backend

Login fails or CORS errors in the browser

CORS-style errors often mean the backend is not reachable. First confirm the backend is running (e.g. curl -k https://localhost:8000/admin/). If the backend is up and login still fails, try a different browser or clear site data.

Access container shell

To get a bash shell inside a running container:

# Kesäseteli backend
docker compose -f compose/employer.dev.yml exec backend bash

# Benefit backend
docker compose -f compose.benefit.yml exec backend bash

# Or using container name directly
docker exec -it kesaseteli-backend bash
docker exec -it benefit-backend bash

Publishing with Release Please & Git workflow

Release Please is used to automate release and release tag creation. Release Please creates release pull requests when the main branch has new commits after the last release, with commit messages prefixed with specific Conventional Commits types (feat:, fix: or deps:). More info about types here. Release PR might also already exist (if not merged before). Merging release PR creates appropriate release tag which triggers staging + production deploy. Refer to the Release Please docs.

More information in Confluence.

Basics

• Merge to main branch triggers dev + test deploys. Merging release pull requests created by Release Please triggers staging + production deploys.
• Use Conventional Commits
• Merge with merge commit is disabled on pull requests as it doesn't play well with Release Please. Release Please documentation recommends using squash merge, so keep PR's small enough so that squashing makes sense. Rebase and merge also works if PR is large. More info about merge methods in GitHub docs.
• Pull request title should include Jira handle (for Jira integration to work)
• Release Please figures out how much to increase the version number based on commit messages. Look SemVer and Release Please docs.

Example workflow

1. Branch off from main to feature branch named after Jira handle, e.g. git checkout -b hl-123-new-feature
2. Do your changes & commit using Conventional Commits, e.g. git commit -m "feat: new feature backend"
3. Make additional changes & commit, e.g. git commit -m "feat: new feature frontend"
4. Open a pull request, for example with title HL-123: New feature
5. After PR checks are passed and PR is approved, merge with squash merge (set commit message to e.g. feat: new feature) or rebase and merge
6. Release Please opens release PR with a title similar to this: chore(main): release benefit-backend 1.1.1
7. Merge release pull request to main. This creates a versioned release tag (e.g. benefit-backend: v1.1.1) that triggers staging and production deploy (Deploys still must be approved from Azure DevOps).

Setting up git hooks

Husky wires Git to run scripts in .husky/ when you commit. Those scripts invoke the pre-commit CLI (see .pre-commit-config.yaml) and a few repo-specific steps.

For example, a commit may run:

• Ruff and other checks from .pre-commit-config.yaml (lint, format, whitespace, YAML/TOML, large files, ShellCheck)
• doctoc on staged README.md files
• Lerna-driven frontend pre-commit scripts for frontend (e.g. lint-staged, ESLint, typecheck)
• Conventional commit message checks

See more in .husky/README.md.

After cloning, install root Node dependencies (for Husky, etc.) and wire Git to use Husky:

pnpm install
pnpm husky

Note: you don't need to run pre-commit install, Husky calls pre-commit run directly.

Git hooks can be disabled temporarily with git commit --no-verify.

Kesäseteli employer

YJDH-Kesäseteli service for employers to fulfill employee applications

kesaseteli-employer Development with Docker

Follow the Quick start section above to set up your environment files.

Then run pnpm employer up or, if you want to rebuild, then pnpm employer up --build

• The employer frontend is now running at localhost:3000
• The backend is now running at localhost:8000

If services fail to get up, pnpm clean or docker system prune --all might help.

Kesäseteli youth

YJDH-Kesäseteli service for young people to send kesäseteli applications

kesaseteli-youth development with Docker

Follow the Quick start section above to set up your environment files.

Then run pnpm youth up or, if you want to rebuild, then pnpm youth up --build

• The youth frontend is now running at localhost:3100
• The backend is now running at localhost:8000

If services fail to get up, pnpm clean might help.

Kesäseteli handler

YJDH-Kesäseteli service for city staff to process kesäseteli applications

kesaseteli-handler development with Docker

Follow the Quick start section above to set up your environment files.

Then run pnpm handler up or, if you want to rebuild, then pnpm handler up --build

• The handler frontend is now running at localhost:3200
• The backend is now running at localhost:8000

If services fail to get up, pnpm clean might help.

Benefit

YJDH-Benefit provides two services for applying and for handling the application of discretionary support:

• Service for a private or third-sector employer that hires an unemployed Helsinki resident
• Service for the City Of Helsinki backoffice to handle aforementioned applications

Benefit development with Docker

Follow the Quick start section above to set up your environment files.

Then run pnpm benefit up or, if you want to rebuild, then pnpm benefit up --build

• The Applicant Frontend is now running at localhost:3000
• The Handler Frontend is now running at localhost:3100
• The backend is now running at localhost:8000

Maintaining and known issues

Maintenance tasks (Kesäseteli)

• Annual: Create summer voucher configuration for the new year:

  docker exec -it kesaseteli-backend python manage.py create_summervoucher_configuration --year <YEAR>

• After deploy: Sync email templates from files to database:

  docker exec -it kesaseteli-backend python manage.py ensure_email_templates

• When models change: Update admin permissions (e.g. after registering new models in Django Admin):

  docker exec -it kesaseteli-backend python manage.py setup_admin_permissions

Daily jobs (cleanup of old applications, audit log sending) run via deployment infrastructure. See backend/kesaseteli/README.md for details.

Known issues

GitHub action deploy fails with "rendered manifests contain a resource that already exists"

The branch name is too long. Rename the branch and create a new PR. See StackOverflow.

Git blame ignore refs

Project includes a .git-blame-ignore-revs file for ignoring certain commits from git blame. This can be useful for ignoring e.g. formatting commits, so that it is more clear from git blame where the actual code change came from. Configure your git to use it for this project with the following command:

git config blame.ignoreRevsFile .git-blame-ignore-revs