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
All Docker images are published on GitHub Container Registry (ghcr.io/open-ksef/*) and do not require authentication.
| Image | Description |
|---|---|
openksef-keycloak | Keycloak 26 with built-in OpenKSeF realm (3 OAuth clients: API, mobile, portal-web) |
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) |
Keycloak and gateway have their 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) |
GOOGLE_CLIENT_ID | Google OAuth Client ID (for Google sign-in) |
GOOGLE_CLIENT_SECRET | Google OAuth Client Secret |
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 three modes:
| Mode | Description |
|---|---|
Token | Token authentication (default) |
Certificate | Certificate authentication |
Auto | Token until January 1, 2027, then certificate |
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