Configuration
OpenKSeF can be configured in three ways (in order of priority):
- Setup wizard (recommended) -- web wizard at
/admin-setup, saves settings in the database (system_config) .envfile -- environment variables next todocker-compose.yml- Default values -- built into
docker-compose.yml
Priority: Setup wizard (database) > .env file > default values
For a standard installation, you don't need to create an .env file -- just start the stack and go through the setup wizard. The .env file is useful when you want to change ports, database passwords, or the public URL before the first launch.
Container architecture
Application images are published on GitHub Container Registry (ghcr.io/open-ksef/*) and do not require authentication. Keycloak uses the official image (quay.io/keycloak/keycloak:26.0).
| Image | Description |
|---|---|
keycloak/keycloak:26.0 | Keycloak 26 (official image). The openksef realm and OAuth clients are created by the setup wizard |
openksef-gateway | Nginx with built-in reverse proxy configuration (portal /, API /api/*, Keycloak /auth/*) |
openksef-api | .NET 8 backend |
openksef-worker | .NET 8 worker (background invoice synchronization) |
openksef-portal-web | React portal (SPA) |
The gateway has its configuration built into the image. No need to mount config files or volumes (except the PostgreSQL data volume).
Required variables (API / Worker)
| Variable | Description | Default |
|---|---|---|
ConnectionStrings__Db | PostgreSQL connection string | Host=postgres;Database=openksef;... |
Auth__Authority | Keycloak realm URL | http://keycloak:8080/auth/realms/openksef |
ENCRYPTION_KEY | AES-256 key for encrypting KSeF tokens | (generated by wizard) |
KSeF__BaseUrl | KSeF API address | https://ksef-test.mf.gov.pl/api |
Required variables (Web Portal)
| Variable | Description | Default |
|---|---|---|
VITE_API_BASE_URL | API URL for the portal | /api |
VITE_AUTH_AUTHORITY | Keycloak URL for OIDC | /auth/realms/openksef |
VITE_AUTH_CLIENT_ID | Client ID in Keycloak | openksef-portal-web |
Infrastructure variables
| Variable | Description | Default |
|---|---|---|
POSTGRES_USER | PostgreSQL user | openksef |
POSTGRES_PASSWORD | PostgreSQL password | openksef_dev_password |
KEYCLOAK_ADMIN | Keycloak admin login | admin |
KEYCLOAK_ADMIN_PASSWORD | Keycloak admin password | admin |
KC_DB_USERNAME | Keycloak database user (if different from Postgres) | value of POSTGRES_USER |
KC_DB_PASSWORD | Keycloak database password (if different from Postgres) | value of POSTGRES_PASSWORD |
For production deployments, change the default passwords in the .env file. Default values (openksef_dev_password, admin) are intended for development purposes only.
Optional variables
| Variable | Description |
|---|---|
APP_EXTERNAL_BASE_URL | Public instance URL (e.g. http://192.168.1.50:8080) |
API_CLIENT_SECRET | Secret for openksef-api client in Keycloak (generated by wizard) |
FIREBASE_CREDENTIALS_JSON | Firebase service account JSON (for direct push) |
SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASSWORD | Mail configuration (email fallback) |
KSeF environments
| Environment | URL | Usage |
|---|---|---|
| Test | https://ksef-test.mf.gov.pl/api | Development and testing |
| Production | https://ksef.mf.gov.pl/api | Real invoices |
The production KSeF environment operates on real tax data. Make sure your instance is properly secured before switching to production.
KSeF authentication mode
The KSeF__AuthMode variable supports two modes:
| Mode | Description |
|---|---|
Token | Token authentication (default) |
Certificate | Certificate authentication |
Ports
Ports can be customized in .env:
APP_HOST_PORT=8080
API_HOST_PORT=8081
KEYCLOAK_HOST_PORT=8082
PORTAL_WEB_HOST_PORT=8083
POSTGRES_HOST_PORT=5432