Configure Kuvasz
Kuvasz can be configured in two ways: via a YAML configuration file, or via environment variables. Most of the configuration options are available in both formats, but some are only available in one of them.
Info
The YAML configuration file should be mounted as a volume in the Docker container under /config/kuvasz.yml.
Tip
If you modify your configuration (via YAML or ENV, it doesn't matter), you need to restart the Kuvasz container for the changes to take effect.
Authentication
Toggling authentication
2.0.0
true
boolean
If it's set to false, the authentication will be completely disabled, and you can access the web UI or the API without any credentials.
Disabling authentication
If you disable authentication, anyone can access your Kuvasz instance (assuming that it's exposed), so make sure to secure it by other means, like a firewall or a reverse proxy with authentication.
If you're running it locally, or on your private network, it might be fine, but be aware of the risks.
Authentication max age
2.0.0
86400
number
The maximum age of the authentication token in seconds, default is 24 hours (86400 seconds). After this time, the admin user will need to log in again on the web UI.
Credentials
Admin username
The username for the admin user.
Admin password
The password for the admin user, minimum 12 characters long, can't be the same as the username.
API key
2.0.0
auth enabled
string
The API key for the REST API, minimum 16 characters long.
Database
Kuvasz uses a PostgreSQL database to store its data. You can use an existing PostgreSQL instance, and point Kuvasz to a separate database in it, the only thing you should watch out for is that the database user has the necessary permissions to create schemas and tables.
The database connection can be configured only via environment variables.
Info
The minimum, tested version of PostgreSQL is 12, alpine distributions are supported.
Host
A hostname or IP address of the database server.
Port
Database name
The name of the database to connect to. Kuvasz will create a schema called kuvasz in the database, and will use it to store all the data it needs.
User
The username to connect to the database. The user must have the necessary permissions to create schemas and tables.
Password
The password of the user above.
SMTP
Tip
Using an SMTP server is optional, it's only needed if you want to use the email integration to send notifications about events.
The SMTP configuration can be set only via YAML.
Be aware that if you include smtp-config in your configuration, then you'll need to provide all the required properties of it, otherwise Kuvasz won't start.
Host
2.0.0
smtp-config is present
string
The hostname or IP address of the SMTP server you want to use for sending emails.
Port
2.0.0
smtp-config is present
number
The port of the SMTP server you want to use for sending emails.
Username
2.0.0
null
string
The username to authenticate with the SMTP server. If your SMTP server doesn't require authentication, you can omit specifying this property, or set it explicitly to null.
Password
2.0.0
null
string
The password to authenticate with the SMTP server. If your SMTP server doesn't require authentication, you can omit specifying this property, or set it explicitly to null.
Transport strategy
2.0.0
SMTP_TLS
enum: SMTP_TLS, SMTPS, SMTP
The transport strategy to use for sending emails. The default is SMTP_TLS, which uses TLS encryption for the connection. You can also use SMTPS (implicit SSL) or SMTP (no encryption).
Miscellaneous
Timezone
The timezone to use for the application. It's recommended to set it to your local timezone.
Event data retention
2.0.0
365
number
The number of days to keep the finished events in the database. After this time, finished uptime & SSL events will be cleaned up to spare space in the database. The minimum is 1 day.
Latency data retention
2.0.0
7
number
The number of days to keep the latency data in the database. After this time, latency data will be cleaned up to spare space in the database. The minimum is 1 day.
Event logging
Toggles the log based event handler, which writes the uptime & SSL events coming from monitors (i.e. UP/DOWN/redirect/etc.) to the STDOUT of the container.
Examples:
✅ Your monitor "test_up" (https://test.com) is UP (200). Latency was: 1826ms.🚨 Your monitor "test_down" (https://test2.com) is DOWN. Reason: Connect Error: Connection refused: test2.comℹ Request to "test_redirected" (https://redirected.com) has been redirected🔒️ Your site "test_good_ssl" (https://good-ssl.com) has a VALID certificate🚨 Your site "test_bad_ssl" (https://no-subject.badssl.com/) has an INVALID certificate. Reason: PKIX path validation failed
Language
2.0.0
en
string
The language to use. Currently, only en (English) is supported, but more languages will be added in the future. See the Localization section for more details.
Full configuration example
You can find the full configuration example below, which includes all the options mentioned above. You can use it as a starting point for your own configuration.
micronaut.security.enabled: true
micronaut.security.token.generator.access-token.expiration: 86400 # 24 hours
---
admin-auth:
username: YourSuperSecretUsername
password: YourSuperSecretPassword
api-key: ThisShouldBeVeryVerySecureToo
---
app-config:
event-data-retention-days: 365 # 1 year
latency-data-retention-days: 7 # 1 week
log-event-handler: true
language: en
---
smtp-config:
host: 'your.smtp.server'
port: 465
transport-strategy: SMTP_TLS
username: YourSMTPUsername
password: YourSMTPPassword
ENABLE_AUTH=true
AUTH_MAX_AGE=86400 # 24 hours
ADMIN_USER=YourSuperSecretUsername
ADMIN_PASSWORD=YourSuperSecretPassword
ADMIN_API_KEY=ThisShouldBeVeryVerySecureToo
DATABASE_HOST=localhost
DATABASE_PORT=5432
DATABASE_NAME=postgres
DATABASE_USER=change_me
DATABASE_PASSWORD=change_me
EVENT_DATA_RETENTION_DAYS=365 # 1 year
LATENCY_DATA_RETENTION_DAYS=7 # 1 week
ENABLE_LOG_EVENT_HANDLER=true
APP_LANGUAGE=en
TZ=UTC