-
Notifications
You must be signed in to change notification settings - Fork 8
Configuring Surface
Gustavo Silva edited this page Feb 16, 2023
·
2 revisions
This page highlights the existing Surface configuration options for end-users installing and running the application. These allow configuring some mandatory dependencies, like databases, but also contain optional tweaks you can add, depending on what Django apps you have installed.
Some of these variables are considered secrets and sensitive data, and therefore users are discouraged from hardcoding them in the code. Consider using them through environment variables or any other form of secret injection that is available to you. It's also recommended to visit Django's official settings list learn about other options users have available to configure Django, although some options are referred in the following table as well.
The below recommendations is based on environment variables for simplicity.
Setting (in your surface/settings.py) |
Recommended value | Description |
|---|---|---|
| SURF_DATABASE_URL (mandatory) | ENV_VAR.db('SURF_DATABASE_URL', default='sqlite:////' + str(BASE_DIR / 'db.sqlite3')) |
This option lets you configure the database URL Django should use. Defaults to a local sqlite3 database |
| SURF_DATABASE_USER (mandatory if MySQL or PostgreSQL, optional if SQLite) | ENV_VAR('SURF_DATABASE_USER') |
User to connect to the database (it's possible to configure authentication for SQLite databases) |
| SURF_DATABASE_PASSWORD (mandatory if MySQL or PostgreSQL, optional if SQLite) | ENV_VAR('SURF_DATABASE_PASSWORD') |
Password of the user to connect to the database. |
| SURF_DEBUG (optional) | ENV_VAR.bool('SURF_DEBUG', default=True) |
Whether to run Django in debug mode or not. In production this option should be false as it is a security risk. |
| SURF_ALLOWED_HOSTS (optional) | ENV_VAR.list('SURF_ALLOWED_HOSTS', default=['127.0.0.1', 'localhost']) |
This option allows configuring hosts to which Django serves to. |
| AVZONE (optional) | ENV_VAR('SURF_AVZONE', default='dev') |
This variable allows configuring an availability zone for surface. |
Setting (in your surface/settings.py) |
Recommended value | Description |
|---|---|---|
| SCANNERS_REGISTRY_AUTH (optional) | ENV_VAR.json('SURF_SCANNERS_REGISTRY_AUTH', default={}) |
Add private registries for the scanner framework to connecto to. This should be a map of key/value objects like: "ghcr.io": {'username': 'something', 'password': ENV_VAR('SURF_SCANNERS_REGISTRY_TOKEN', default=None)
|
| SCANNERS_REGISTRY_TOKEN (optional) | ENV_VAR('SURF_SCANNERS_REGISTRY_TOKEN') |
The token used to access the configured registry. This variable is recommended when using the setup described in SCANNERS_REGISTRY_AUTH. |
| SCANNERS_DOCKER_CA_CERT (optional) | ENV_VAR('SURF_SCANNERS_DOCKER_CA_CERT', default=None) |
These and the following DOCKER variables allows securing the Docker socket to use HTTPS instead of SSH, should you need Docker to be safely available through the network, by providing a CA, private keys and the client certificates. For more details, see Docker official documentation
|
| SCANNERS_DOCKER_CA_CERT_PATH (optional) | ENV_VAR('SURF_SCANNERS_DOCKER_CA_CERT_PATH', default=None) |
For more details, see Docker official documentation |
| SCANNERS_DOCKER_CLIENT_KEY (optional) | ENV_VAR('SURF_SCANNERS_DOCKER_CLIENT_KEY', default='') |
For more details, see Docker official documentation |
| SCANNERS_DOCKER_CLIENT_KEY_PATH (optional) | ENV_VAR('SURF_SCANNERS_DOCKER_CLIENT_KEY_PATH', default='') |
For more details, see Docker official documentation |
| SCANNERS_DOCKER_CLIENT_CERT (optional) | ENV_VAR('SURF_SCANNERS_DOCKER_CLIENT_CERT', default='') |
For more details, see Docker official documentation |
| SCANNERS_DOCKER_CLIENT_CERT_PATH (optional) | ENV_VAR('SURF_SCANNERS_DOCKER_CLIENT_CERT_PATH', default='') |
For more details, see Docker official documentation |
Setting (in your surface/settings.py) |
Recommended value | Description |
|---|---|---|
| DKRON_URL (optional) | ENV_VAR('SURF_DKRON_URL', default='http://localhost:8888/') |
This variable should only be used when django-dkron is installed. It is used to specify the Dkron server location. For more details, check the project page and wiki. |
| DKRON_TOKEN (optional) | ENV_VAR('SURF_DKRON_TOKEN', default=None) |
This variable should only be used when django-dkron is installed and it's used to configure the token used by run_dkron for webhook calls. |
| DKRON_BIN_DIR (optional) | ENV_VAR('SURF_DKRON_BIN_DIR', default=BASE_DIR.parent / 'dev' / 'dkron') |
This variable should only be used when django-dkron is installed. This directory is used to store and execute the dkron binaries and defaults to temporary one, which is hardly optimal. Set one up. |
| DKRON_TAGS (optional) | ENV_VAR.list('SURF_DKRON_TAGS', default=[]) |
This variable should only be used when django-dkron is installed. It allows configuring which tags used by the dkron server and agent. |
| DKRON_JOB_LABEL (optional) | ENV_VAR('SURF_DKRON_JOB_LABEL', default='surf') |
This variable should only be used when django-dkron. It allows configure labels for jobs triggered by run_dkron, which ensures the dkron only runs jobs created by this app. |
| DKRON_JOIN (optional) | ENV_VAR.list('SURF_DKRON_JOIN', default=None) |
This variable should only be used when django-dkron. It sets which agents to join with when starting. |
| DKRON_ENCRYPT (optional) | ENV_VAR('SURF_DKRON_ENCRYPT', default=None) |
This variable should only be used when django-dkron. Encryption key for run_dkron. |
| DKRON_WORKDIR (optional) | ENV_VAR('SURF_DKRON_WORKDIR', default=BASE_DIR) |
This variable should only be used when django-dkron. Working directory for run_dkron. |
| DKRON_SERVER (optional) | ENV_VAR('SURF_DKRON_SERVER', default=True) |
This variable should only be used when django-dkron. This sets dkron in server mode, the recommended setting. |
| DKRON_API_AUTH (optional) | ENV_VAR('SURF_DKRON_API_AUTH', default=None) |
This variable should only be used when django-dkron. HTTP Basic Auth header value, really recommended when dkron is publicly exposed. |
| DKRON_VERSION (optional) | ENV_VAR('SURF_DKRON_VERSION', default='3.1.10') |
This variable should only be used when django-dkron. This sets the dkron version to (download and) use. |
| DKRON_WEBHOOK_URL (optional) | ENV_VAR('SURF_DKRON_WEBHOOK_URL', default=None) |
This variable should only be used when django-dkron. This sets the webhook URL dkron will post job status. This setting requires mapping dkron.views.webhook in your project urls.py file and this should be full URL to that route and reachable by dkron. |
| DKRON_NAMESPACE (optional) | ENV_VAR('SURF_DKRON_NAMESPACE', default=None) |
This variable should only be used when django-dkron. This setting allows configuring different namespace prefixes for jobs created and run by this app so that the same dkron cluster can be used by multiple apps without conflicting job names. |
| DKRON_NODE_NAME (optional) | ENV_VAR('SURF_DKRON_NODE_NAME', default=None) |
This variable should only be used when django-dkron. This setting configures a key used for encrypting network traffic. Must be a base-64 16-byte key. |
Setting (in your surface/settings.py) |
Recommended value | Description |
|---|---|---|
| NOTIFICATIONS_SLACK_APP_TOKEN (optional) | ENV_VAR('SURF_NOTIFICATIONS_SLACK_APP_TOKEN', default=None) |
This variable should only be used when django-notification-sender is installed. This configures the slack app token used to send notifications to Slack. For more details, check the project page and wiki. |
| NOTIFICATIONS_MAIL_FROM (optional) | ENV_VAR('SURF_NOTIFICATIONS_MAIL_FROM', default=None) |
This variable should only be used when django-notification-sender is installed. This configures the email from which email notifications are sent from. For more details, check the project page and wiki. |
Setting (in your surface/settings.py) |
Recommended value | Description |
|---|---|---|
| SLACKBOT_BOT_TOKEN (optional) | ENV_VAR('SURF_SLACKBOT_BOT_TOKEN', default=None) |
This variable should only be used when django-slack-processor is installed. It configures the token used by the Slack bot to interact. For more details, check the project page and wiki. |
| SLACKBOT_APP_TOKEN (optional) | ENV_VAR('SURF_SLACKBOT_APP_TOKEN', default=None) |
This variable should only be used when django-slack-processor is installed. It configures the token used by the Slack bot to interact. For more details, check the project page and wiki. |
Before releasing your application to production, it's recommended to visit Django's official Deployment Checklist for a full list of recommended checks for Django applications.