DevOps - ITKsites

This is our internal server and site registration tool. It works in tandem with our ITK sites server harvester. The harvester is installed by default on all servers, and runs at intervals and collects information about sites and installations running on the server. These are sent as DetectionResults to ITKsites where they are analysed and processed.

This allows us to monitor

• What is installed and running
• Which sites/domains we are hosting
• What docker images we are running
• What packages and modules we are running
• If there are known CVE's for the packages/modules
• What git repositories we are hosting

Additionally we can register and document

• All OpenID Connect setups
• All Services Certificates

Servers, OpenID Connect setups, Services Certificates must be created and maintained manually. All other information is kept up to date by analysing the DetectionResults.

Architecture

This is a Symfony 6 project build with api-platform 3.x and EasyAdmin.

Api-platform provides a simple REST api for POST'ing the DetectionResults. These are then processed asynchronously by a series of message handlers.

EasyAdmin is used to provide an interface to view and search the analyzed data, as well as editing the data that must updated manually.

The system is build so that all analyzed data can be truncated safely and rebuild by "replaying" the DetectionResults. This means that care must be taken when manually maintained data and auto updated data must have cross references.

Development

docker compose pull
docker compose up --detach
docker compose exec phpfpm composer install
docker compose exec phpfpm bin/console doctrine:migrations:migrate --no-interaction

Then create a .env.local file to set secrets for your local setup.

OpenID Connect

All users access is controlled by OpenID Connect. For local development you must add the following to your .env.local file:

###> itk-dev/openid-connect-bundle ###
AZURE_AZ_OIDC_METADATA_URL=<value>
AZURE_AZ_OIDC_CLIENT_ID=<value>
AZURE_AZ_OIDC_CLIENT_SECRET=<value>
AZURE_AZ_OIDC_REDIRECT_URI=https://itksites.local.itkdev.dk/openid-connect/generic
###< itk-dev/openid-connect-bundle ###

Note

In the dev environment the main firewall security is disabled (security.yaml → when@dev), so authentication is not required. This is because the current AAK OIDC setup doesn't support itksites.local.itkdev.dk.

Fixtures

There are not implemented on

• sites
• installations
• domains

This is due to automated processes and scripts that listen from sites and data is therefore not relevant to have. The architecture makes it possible to delete all the above data.

Load fixtures

docker compose exec phpfpm composer fixtures

After loading fixtures you can sign in as an admin user:

docker compose exec phpfpm bin/console itk-dev:openid-connect:login admin@example.com

Job queues and handlers

All processing of Detctionresults is done in a series of message handlers. To run these do either:

docker compose exec phpfpm composer queues

or

docker compose exec phpfpm bin/console messenger:consume async --failure-limit=1 -vvv

Assets

We use Webpack Encore to build assets:

docker compose run --rm node yarn install
docker compose run --rm node yarn build

Use

docker compose run --rm node yarn watch

during development to automatically rebuild assets when source files change.

Coding standards

docker compose run --rm node yarn coding-standards-check

🤖 AI coding agents

This project includes an claude.md file that provides project context for Claude Code. The file describes the project architecture, technology stack, development commands, CI/CD setup, and coding conventions.

Tool-specific configuration (permissions, hooks, plugins) lives in .claude/ and is not portable across tools.

Note

agents.md is a vendor-neutral standard supported by tools such as OpenCode and others. Claude Code doesn't currently support agents.md, claude.md should be renamed to a vendor neutral standard when Claude supports it.

Claude Code plugins

The following plugins are enabled in .claude/settings.json:

Plugin	Purpose	Source
php-lsp	PHP language server for type-aware code intelligence	claude-plugins-official
context7	Up-to-date documentation lookup for Symfony, Doctrine, API Platform, etc.	claude-plugins-official
code-review	Pull request code review	claude-plugins-official
code-simplifier	Suggests clarity and maintainability improvements	claude-plugins-official
security-guidance	Flags potential security issues (OWASP, injection, etc.)	claude-plugins-official
playwright	Browser automation for debugging and testing the EasyAdmin UI	claude-plugins-official
feature-dev	Guided feature development with codebase exploration and architecture focus	claude-plugins-official

Note: The php-lsp plugin requires Intelephense installed globally: npm install -g intelephense. All other plugins work without additional dependencies.

Claude Code agents

Custom agents in .claude/agents/ automate multi-step workflows:

Agent	Purpose
pr-readiness	Runs all CI-equivalent checks locally before creating a PR
create-migration	Generates and validates a Doctrine migration after entity changes

Claude Code skills

Custom skills in .claude/skills/ provide repeatable task shortcuts:

Skill	Invocation	Purpose
update-api-spec	/update-api-spec	Regenerate and stage OpenAPI spec files after changes

Claude Code hooks

Hooks in .claude/settings.json run automatically on tool events:

Hook	Trigger	Purpose
Docker start	SessionStart	Starts Docker services on session start
PHP-CS-Fixer	PostToolUse	Auto-formats PHP files on edit
PHPStan	PostToolUse	Runs static analysis on edited PHP files
Twig-CS-Fixer	PostToolUse	Auto-formats Twig templates on edit
Composer norm	PostToolUse	Normalizes composer.json on edit
Prettier	PostToolUse	Auto-formats JS, CSS, YAML, and Markdown files on edit
Lock guard	PreToolUse	Blocks edits to lock files and .env.local
Container lint	Stop	Validates Symfony DI container before stopping

MCP servers

A shared .mcp.json provides team-wide MCP server configuration:

Server	Purpose
context7	Live documentation lookup for Symfony, Doctrine, API Platform, and others