Management Errata is a web interface for managing vulnerabilities. This interface allows you to create, edit and change Errata, and also view the change history.
  • TypeScript 98.2%
  • CSS 1.1%
  • Shell 0.4%
  • Dockerfile 0.2%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
Dmitry Lyalyaev 0b21731d21
All checks were successful
CI / Prepare dependencies (push) Successful in 48s
CI / Build (push) Successful in 52s
CI / Tests (push) Successful in 53s
CI / Code quality (push) Successful in 1m9s
Merge pull request 'docs(readme): document AGENTS.md and fix outdated project references' (#507) from update-readme into master
Reviewed-on: #507
Reviewed-by: Dmitry Lyalyaev <fruktime@altlinux.org>
2026-11-03 14:23:35 +03:00
.forgejo chore: update copyright headers to 2021-2026 2026-10-13 11:07:56 +03:00
.husky chore(husky): drop NODE_OPTIONS=--experimental-strip-types from pre-commit 2026-09-14 16:57:43 +03:00
docs Merge pull request 'docs(adr): update architecture decision records to match new tech stack' (#505) from update-adr into master 2026-11-03 12:40:43 +03:00
nginx feat(nginx): send a report-only Content-Security-Policy 2026-10-06 17:44:32 +03:00
public chore: update copyright headers to 2021-2026 2026-10-13 11:07:56 +03:00
src refactor(views,routes): replace NotFound with EmptyStatePage and per-entity not-found messages 2026-10-28 12:08:37 +03:00
.dockerignore docker: Dockerizing App for Development and Production 2023-09-26 14:57:07 +03:00
.env.example docs: name the real API host in the configuration examples 2026-10-06 17:44:32 +03:00
.gitignore feat(api): add mock generation and split generated outputs 2026-09-17 16:18:32 +03:00
.npmrc refactor: migrate alt-releases-matrix-ts from system package to npm 2026-09-16 11:32:07 +03:00
.prettierrc refactor: add prettier, config and format project 2025-11-19 16:12:52 +03:00
AGENTS.md docs(agents): add AGENTS.md with AI agent working rules 2026-10-28 12:37:47 +03:00
CHANGELOG.md refactor(views,routes): replace NotFound with EmptyStatePage and per-entity not-found messages 2026-10-28 12:08:37 +03:00
deploy.sh chore: update copyright headers to 2021-2026 2026-10-13 11:07:56 +03:00
docker-compose.yml chore: update copyright headers to 2021-2026 2026-10-13 11:07:56 +03:00
Dockerfile chore: update copyright headers to 2021-2026 2026-10-13 11:07:56 +03:00
eslint.config.ci.ts refactor(eslint-ci): reuse base config for CI to remove duplication 2026-10-14 14:34:59 +03:00
eslint.config.ts chore(eslint): enforce AGPL copyright headers in TypeScript files 2026-10-14 14:32:01 +03:00
index.html chore: update copyright headers to 2021-2026 2026-10-13 11:07:56 +03:00
lint-staged.config.ts chore: update copyright headers to 2021-2026 2026-10-13 11:07:56 +03:00
orval.config.ts chore: update copyright headers to 2021-2026 2026-10-13 11:07:56 +03:00
package.json Merge pull request 'feat(auth): sign in with Kanidm through oidc-client-ts' (#468) from ancieg/management_errata:feat/kanidm-oidc into master 2026-10-16 17:25:44 +03:00
pnpm-lock.yaml Merge pull request 'feat(auth): sign in with Kanidm through oidc-client-ts' (#468) from ancieg/management_errata:feat/kanidm-oidc into master 2026-10-16 17:25:44 +03:00
pnpm-workspace.yaml fix: move saveExact to pnpm-workspace.yaml due to npmrc being ignored 2026-10-12 17:43:50 +03:00
README.md Merge pull request 'docs(readme): document AGENTS.md and fix outdated project references' (#507) from update-readme into master 2026-11-03 14:23:35 +03:00
tsconfig.json refactor(ci, docker, configs): remove alt-releases-matrix-ts system package references 2026-09-16 11:42:05 +03:00
vite.config.ts chore: update copyright headers to 2021-2026 2026-10-13 11:07:56 +03:00
vitest.config.ts chore: update copyright headers to 2021-2026 2026-10-13 11:07:56 +03:00

Table of Contents

Management Errata

Management Errata is a web application for vulnerability management that tracks vulnerability statuses for ALT Linux packages and creates Errata records.

It generates Errata based on task and branch history, stores change history, and ensures consistency of vulnerability mappings over time. The service supports both automatic generation (tasks, branches, updates) and manual verification (SA, Errata, CPE/PNC mappings).

More details are available in the documentation.

License

GNU AGPLv3

Dependencies

Main Dependencies

Dependency Purpose
React 19 UI framework for building the application interface
TypeScript Static typing and improved maintainability
Vite Fast development server and optimized production builds
PatternFly Enterprise UI component library used across the application
React Router Client-side routing and navigation
TanStack Query Server state management, caching and asynchronous data fetching
MobX Local and shared client-side state management
Axios HTTP client for API communication
React Hook Form Form state management and validation
Orval OpenAPI-based API client generation
oidc-client-ts OpenID Connect sign-in (Kanidm) and token renewal

Full list in package.json

Scripts

The project uses npm scripts to manage development, build, testing, and code quality workflows.

Development

Command Description
pnpm start Starts Vite development server
pnpm build Builds production bundle
pnpm preview Serves production build locally

API

Command Description
pnpm api:generate Generates API client, types, and React Query hooks using Orval

Code Quality

Command Description
pnpm lint Runs ESLint and TypeScript type checking
pnpm eslint Runs ESLint only
pnpm eslint:ci Runs ESLint only for CI
pnpm eslint:fix Auto-fixes ESLint issues
pnpm type:check Runs TypeScript type checking
pnpm react-doctor Runs React doctor scanning
pnpm react-doctor:ci Runs React doctor scanning for ci

Formatting

Command Description
pnpm format Formats entire codebase using Prettier
pnpm format:check Checks formatting without modifying files

Testing

Command Description
pnpm test Runs Vitest in watch mode
pnpm test:run Runs tests once (CI mode)
pnpm test:coverage Runs tests with coverage report
pnpm test:clear-cache Clears vitest cache

Git Hooks

Command Description
pnpm prepare Installs Husky Git hooks

This is automatically executed after pnpm install.

Project Structure

├── src/                    # Source code
│ ├── api/                  # API client, Axios instance, type-guards
│ │ └── generated/          # Generated API hooks, models and mocks (Orval)
│ ├── components/           # React components (domain-specific + shared UI)
│ ├── hooks/                # Custom hooks by domain
│ ├── stores/               # MobX stores
│ ├── views/                # Page-level route components
│ ├── utils/                # Utilities
│ ├── services/             # Application services
│ ├── types/                # TypeScript types
│ ├── routes/               # Routing definitions
│ ├── testing/              # Test helpers, fixtures and MSW mocks
│ └── styles/               # Global styles
├── docs/                   # Project documentation
│ ├── adr/                  # Architecture Decision Records
│ └── CODESTYLE.md          # Coding conventions
├── public/                 # Static assets and application documentation
├── nginx/                  # Nginx configuration for Docker
├── AGENTS.md               # Rules for AI coding agents
├── docker-compose.yml      # Docker Compose
└── Dockerfile              # Docker image

Getting Started

1. Clone repository

git clone https://altlinux.space/ALTLinux/management_errata.git
cd management_errata

2. Configure environment variables

Create a local .env file from the example:

cat .env.example > .env

The application relies on a backend API for correct operation and code generation.

The project is designed to work with the API: https://altlinux.space/ALTLinux/altrepoapi

You must provide a valid API url via:

VITE_APP_API_URL

Without it runtime requests will not work.


3. Install dependencies

pnpm ci

This installs dependencies strictly according to pnpm-lock.yaml, ensuring deterministic builds across environments.

Do not use pnpm install, as it may modify pnpm-lock.yaml and introduce version drift.

Note: The API client is generated automatically during the installation process via the postinstall script.


4. Start development server

pnpm start

Application will be available by default at:

http://127.0.0.1:3000

Environment Variables

Required configuration

VITE_APP_API_URL=https://rdb.altlinux.org

Defines backend API base URL. Required for runtime requests.


Authentication (OpenID Connect)

VITE_APP_OIDC_AUTHORITY=https://idm.altlinux.space/oauth2/openid/errata
VITE_APP_OIDC_CLIENT_ID=errata
VITE_APP_OIDC_SCOPE="openid profile"
VITE_APP_OIDC_ROLES_CLAIM=roles

People sign in at the OpenID Connect provider (Kanidm) with the authorisation code flow and PKCE. The site is a public client: it holds no secret. VITE_APP_OIDC_AUTHORITY is the issuer of the site's client, from which the discovery document is read; with Kanidm it is https://<kanidm>/oauth2/openid/<client id>.

The client must list <site>/forge/auth-callback, exactly, as a redirect URL.

Tokens are kept in memory only, as keycloak-js kept them: a reload or a new tab goes through the provider and back, without a password while the provider's own session lasts. The access token is renewed with the refresh token before it expires, and again when the API answers 401; only a session that can no longer be renewed sends the user back to the provider.

Kanidm ends the whole session when a refresh token is presented twice. Each tab signs in on its own and holds a refresh token no other tab has, not even a duplicate of the tab, and renews it one request at a time.

Signing out ends the site's session only. The site revokes its refresh token at the provider's revocation endpoint, which ends that session and no other, and the tab the user signed out in leaves for the front page of the origin (/); the other tabs show a signed-out page. The provider's own session stays, and so does every other site signed in through it. All tabs of the site sign out together, and every tab -- a reload, a new one -- stays signed out until the user signs in again; that sign-in asks the provider for credentials anew (prompt=login select_account), for any account, and the other tabs then follow it through the provider's session.

Asking for credentials anew relies on prompt=login, which needs Kanidm 1.11 or later: older versions ignore the parameter, or let a session that signed in recently through, and the user is back without seeing a password prompt. (Kanidm has no account picker to offer, so select_account is ignored.)

The revocation is a call from the browser, so it depends on the provider answering cross-origin (CORS) requests on its revocation endpoint. If it does not, the call is blocked: the site signs out all the same, and the session at the provider lives on until its tokens expire.

Roles are the values of the ID token claim VITE_APP_OIDC_ROLES_CLAIM, which Kanidm fills from the client's claim map; they update with every renewal. The site and the API use the same client: VITE_APP_OIDC_CLIENT_ID here is the API's KANIDM_CLIENT_ID, and the claim is its KANIDM_ROLES_CLAIM.


User Groups

VITE_APP_ADMIN_GROUP=example_admin
VITE_APP_ANALYST_GROUP=example_analyst
VITE_APP_USER_GROUP=example_user

Defines role-based access control groups used in UI and permission logic.


Development flags

VITE_APP_DISABLE_AUTH=false

Development mode: signs in a developer holding every role, without a provider. Honoured only by development builds (pnpm start). Run the API with ALTREPO_API_DEV_MODE=1 alongside, so that it accepts requests without a token.


Local development settings

VITE_APP_HOST=127.0.0.1
VITE_APP_PORT=3000

Controls local dev server binding.


Production build

pnpm build
pnpm preview
  • build generates optimized production bundle
  • preview serves the production build locally

Sign-in: local development notes

Sign-in uses PKCE, which needs crypto.subtle, which browsers offer only in a secure context. http://127.0.0.1 and http://localhost already are one; the steps below are needed only when the dev server is opened by another address.

Chrome insecure origin setup

To allow secure APIs (crypto / auth flows) on a local HTTP origin other than 127.0.0.1 or localhost:

  1. Open:
chrome://flags/#unsafely-treat-insecure-origin-as-secure
  1. Add your local origin, for example:
http://127.0.0.1:3000
  1. Restart Chrome

Verify crypto support

Open DevTools console:

crypto.subtle;

Expected result: SubtleCrypto object (not undefined)


System CA trust

If the backend or the OpenID Connect provider uses self-signed certificates:

sudo cp your-cert.crt /etc/pki/ca-trust/source/anchors/
sudo update-ca-trust

Then reboot system.


Summary of required services

For full development environment:

  • Running altrepoapi backend
  • An OpenID Connect provider (Kanidm) whose clients the backend accepts, or development mode on both sides (VITE_APP_DISABLE_AUTH=true here, ALTREPO_API_DEV_MODE=1 on the API)
  • Valid .env configuration
  • Generated API client via orval

Without these components, application may start but will not be fully functional.

Code Style & Quality

The project enforces consistent code quality and architecture rules via automated tooling and documentation.

Architecture Decisions

All major architectural decisions are documented in:

  • docs/adr/ — Architecture Decision Records

This file contains decisions regarding state management, API layer design, authentication flow, and project structure.

Coding standards

Project-wide coding conventions are defined in:

It includes:

  • naming conventions
  • folder structure rules
  • React component patterns
  • state management guidelines
  • API usage rules

AI Agents

Rules for AI coding agents (project context, search and context-usage guidelines, change size limits, commit policy, verification commands) are defined in AGENTS.md.

Human contributors should follow docs/CODESTYLE.md and the ADRs; AGENTS.md only points agents to these documents and adds agent-specific constraints. For example, agents must not create commits without explicit approval.

Enforced tooling

  • ESLint for static analysis
  • Prettier for formatting
  • TypeScript for type safety
  • Husky + lint-staged for pre-commit validation

Deployment

The application is containerized using Docker and served via Nginx as a static SPA.

Build process

The Docker build consists of two stages:

  1. Build stage

    • Based on ALT Linux p11 image
    • Installs dependencies via pnpm ci
    • Generates API client using Orval
    • Builds production bundle using Vite
  2. Runtime stage

    • Based on Nginx image
    • Serves static assets from /usr/share/nginx/html
    • Uses templated Nginx configuration

Docker Compose

The application is deployed via docker-compose:

services:
  web:
    build:
      dockerfile: Dockerfile
      args:
        - NODE_ENV=${NODE_ENV:-development}
    ports:
      - ${VITE_APP_PORT}:80
    env_file:
      - ./.env

Deployment script

A helper script deploy.sh is used to manage environments:

./deploy.sh prod build
./deploy.sh prod up
./deploy.sh prod down

It supports:

  • environment switching (prod/dev)
  • container lifecycle management
  • automatic .env synchronization
  • Docker Compose orchestration

Runtime configuration

Environment variables are injected at build and runtime stages, including:

  • API endpoint configuration
  • authentication (OpenID Connect)
  • feature flags
  • groups configuration

Production serving

  • Static assets are served via Nginx
  • Gzip/compression handled at server level
  • No Node.js runtime required in production

Documentation

This project uses a custom Markdown rendering pipeline with automatic figure enumeration based on a rehype transformation (rehypeEnumerateFigures).

Because of this, documentation must follow specific rules to ensure correct rendering, numbering, and stable cross-references.

Figures (images)

All images that should be referenced as figures MUST use a title attribute.

How figures are rendered

![Description](images/example.png "figure-id")
  • title = unique figure identifier (do not write to skip enumeration (e.g. inline images))
  • alt = caption text (parses into Рис. {fig_number}. {alt})

An example above renders into:

<figure id="figure-id">
  <img src="images/example.png" />
  <figcaption>Рис. 1. Description</figcaption>
</figure>

Referencing figures

In markdown:

[Рис. {fig_number}](#figure-id)

In html:

<a href="#figure-id">Рис. 1</a>