From 30aa708959472f233c890b6b8c53702f38b498a7 Mon Sep 17 00:00:00 2001
From: Julien Dessaux <julien.dessaux@adyxax.org>
Date: Thu, 1 May 2025 15:52:44 +0200
Subject: [PATCH] feat(admin): add Configuration

---
 Configuration.md | 85 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 85 insertions(+)
 create mode 100644 Configuration.md

diff --git a/Configuration.md b/Configuration.md
new file mode 100644
index 0000000..e590d45
--- /dev/null
+++ b/Configuration.md
@@ -0,0 +1,85 @@
+# Configuration
+
+TfStated is configured by setting environment variables.
+
+## Mandatory environment variables
+
+Two environment variables are required before TfStated can be started
+successfully.
+
+### TFSTATED_DATA_ENCRYPTION_KEY
+
+The `TFSTATED_DATA_ENCRYPTION_KEY` environment variable must contain the global
+encryption key used to encrypt sensitive information in the database. It must be
+a 32 bytes AES key encoded using Base64.
+
+You can generate such a key using OpenSSL:
+
+``` shell
+openssl rand -base64 32
+```
+
+Do not lose this key or you will lose access to all the OpenTofu/Terraform
+states stored in TfStated!
+
+### TFSTATED_SESSIONS_SALT
+
+The `TFSTATED_DATA_SESSIONS_SALT` environment variable must contain the global
+salt used to hash the session identifiers in the database. It must be a 32 bytes
+AES key encoded using Base64.
+
+You can generate such a key using OpenSSL:
+
+``` shell
+openssl rand -base64 32
+```
+
+Losing this key means invalidating all the webui sessions: users will just need
+to refresh their page and log in again.
+
+## Optional environment variables
+
+Most environment variables are completely optional and are provided sane
+defaults.
+
+### TFSTATED_DEBUG
+
+Setting the `TFSTATED_DEBUG` to any non empty value activates debug logs. Debug
+logs are very verbose and include the source file and line number of each log
+function call. This variable is only useful for development purposes and is
+empty by default.
+
+### TFSTATED_HOST
+
+The `TFSTATED_HOST` environment variable controls on which address the `backend`
+service listens on. Defaults to `127.0.0.1`.
+
+### TFSTATED_PORT
+
+The `TFSTATED_PORT` environment variable controls on which TCP port the
+`backend` service listens on. Defaults to `8080`.
+
+### TFSTATED_VERSIONS_HISTORY_LIMIT
+
+The `TFSTATED_VERSIONS_HISTORY_LIMIT` environment variable controls the minimum
+number of versions that need to be kept for each state file. Defaults to `128`.
+
+### TFSTATED_VERSIONS_HISTORY_MINIMUM_DAYS
+
+The `TFSTATED_VERSIONS_HISTORY_MINIMUM_DAYS` environment variable controls the
+minimum number of days for which to keep any state version. The way the
+retention feature is implemented means that state versions that are more recent
+than this number of days are not counted towards the
+`TFSTATED_VERSIONS_HISTORY_LIMIT`.
+
+Defaults to `28`.
+
+### TFSTATED_WEBUI_HOST
+
+The `TFSTATED_WEBUI_HOST` environment variable controls on which address the
+`webui` service listens on. Defaults to `127.0.0.1`.
+
+### TFSTATED_WEBUI_PORT
+
+The `TFSTATED_WEBUI_PORT` environment variable controls on which TCP port the
+`webui` service listens on. Defaults to `8081`.