Kompro

Documentation

Deploy and operate Kompro.

Practical guidance for teams running Kompro in infrastructure they control.

Getting started

Run Kompro in your environment

Kompro is a self-hosted, single-tenant compliance management platform. The application uses a frontend, backend, and PostgreSQL database that your organization configures and operates.

Before you begin

Plan where the application and database will run, how users will authenticate, and how secrets will be managed.

Installation

The official setup guide requires Node.js 18 or later, with Node.js 20 LTS recommended, and PostgreSQL 14 or later. Native build tools are needed for bcrypt dependencies.

 shellnpm run setup
cp backend/.env.example backend/.env
cp frontend/.env.example frontend/.env

Review and update both environment files before starting the application.

Configuration

Backend and frontend configuration are kept separately. The backend requires pooled and direct database connections, a strong JWT secret, and the correct runtime environment. The frontend points to the API.

DATABASE_URL

Pooled PostgreSQL connection used at runtime.

DIRECT_URL

Direct PostgreSQL connection used for migrations.

JWT_SECRET

A strong random secret used for signed sessions.

VITE_API_URL

Use /api for same-origin deployments or a full API URL for split deployments.

Database

Kompro supports PostgreSQL 14 or later. Initialize the database from the backend directory after configuring both database connection values.

 shellnpm run migrate:deploy
npm run seed

The seed command creates the initial administrator and roles. Protect initial credentials and rotate secrets according to your organization’s operating procedures.

Deployment

The documented single-machine model uses Nginx to serve the built frontend and proxy /api requests to the backend. Split-host deployments are also supported, but require HTTPS on both origins and cross-site cookie configuration.

Production note

Set the runtime environment to production for secure cookies. Configure allowed origins narrowly and add an external production-grade rate limit at the infrastructure layer.

Authentication

Kompro supports Google, Microsoft, and GitHub authentication. Your organization supplies the provider credentials through environment configuration.

Built-in TOTP or MFA is not provided. Enforce MFA through your identity provider where required.

Security

Harden the deployment as part of your infrastructure, identity, and secrets management practices.

  • Use HTTPS for all production traffic.
  • Keep JWT and provider secrets out of source control.
  • Restrict CORS to the deployed frontend origin.
  • Enable security headers such as HSTS and CSP at the application or proxy layer.
  • Keep dependencies, PostgreSQL, and the runtime patched.
Report vulnerabilities privately

Do not open a public GitHub issue. Follow the private reporting instructions in the official security policy.

Read SECURITY.md

Upgrading

The current repository documentation does not define a complete upgrade procedure. Before updating, review release notes and repository changes, back up your database, and validate the new version in a non-production environment.

Troubleshooting

Start by checking the application process, database connectivity, environment configuration, allowed origins, and reverse proxy behavior. For project help, use the Help Center or review issues in the official repository.