- TypeScript 98.2%
- CSS 1.1%
- Shell 0.4%
- Dockerfile 0.2%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
|
|
||
| .forgejo | ||
| .husky | ||
| docs | ||
| nginx | ||
| public | ||
| src | ||
| .dockerignore | ||
| .env.example | ||
| .gitignore | ||
| .npmrc | ||
| .prettierrc | ||
| AGENTS.md | ||
| CHANGELOG.md | ||
| deploy.sh | ||
| docker-compose.yml | ||
| Dockerfile | ||
| eslint.config.ci.ts | ||
| eslint.config.ts | ||
| index.html | ||
| lint-staged.config.ts | ||
| orval.config.ts | ||
| package.json | ||
| pnpm-lock.yaml | ||
| pnpm-workspace.yaml | ||
| README.md | ||
| tsconfig.json | ||
| vite.config.ts | ||
| vitest.config.ts | ||
Table of Contents
- Overview
- License
- Dependencies
- Scripts
- Project Structure
- Getting Started
- Environment Variables
- Code Style & Quality
- Deployment
- Documentation
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
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 modifypnpm-lock.yamland 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
buildgenerates optimized production bundlepreviewserves 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:
- Open:
chrome://flags/#unsafely-treat-insecure-origin-as-secure
- Add your local origin, for example:
http://127.0.0.1:3000
- 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
altrepoapibackend - An OpenID Connect provider (Kanidm) whose clients the backend accepts, or development mode on both sides (
VITE_APP_DISABLE_AUTH=truehere,ALTREPO_API_DEV_MODE=1on the API) - Valid
.envconfiguration - 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:
-
Build stage
- Based on ALT Linux p11 image
- Installs dependencies via
pnpm ci - Generates API client using Orval
- Builds production bundle using Vite
-
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
.envsynchronization - 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

- 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>