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.
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/.envReview 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_URLPooled PostgreSQL connection used at runtime.
DIRECT_URLDirect PostgreSQL connection used for migrations.
JWT_SECRETA strong random secret used for signed sessions.
VITE_API_URLUse /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 seedThe 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.
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.
Do not open a public GitHub issue. Follow the private reporting instructions in the official security policy.
Read SECURITY.mdUpgrading
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.
