Este conteúdo não está disponível em sua língua ainda.

Environment Variables

The ALTCHA Sentinel application is configured using environment variables (ENV vars).

Configuring Environment Variables

Environment variables can be set either at runtime or through the application’s administrative interface.

Setting Variables via the Application UI

The application allows you to configure environment variables through its web interface. These settings are stored in the data/.env file.

Steps:

Log in to the application.
Navigate to Admin → ENV Variables.
Add, edit, or remove variables as needed.
Click Save to persist changes.

Setting Variables via Runtime Configuration

For deployments outside the UI (e.g., Docker, systemd, Kubernetes), you can configure environment variables directly through your runtime environment.

Refer to your deployment platform’s documentation for instructions on setting environment variables.

Secret Management Support

ALTCHA Sentinel supports secure handling of sensitive configuration values (like API keys or passwords) by reading values from mounted secret files. This is especially useful in containerized environments like Docker or Kubernetes.

To use a secret file, append _FILE to the environment variable name. The application will read the contents of the specified file and use it as the variable’s value.

Example:

Instead of:

ALTCHA_HMAC_SECRET=my-secret-key

Use:

ALTCHA_HMAC_SECRET_FILE=/run/secrets/ALTCHA_HMAC_SECRET

Ensure that the file at /run/secrets/ALTCHA_HMAC_SECRET contains only the raw secret value.

Default Required Variables

When Sentinel starts up, it checks whether the required environment variables—such as secrets—are set. If any are missing, Sentinel automatically generates random values for them and saves them to the /data/.env file on the persistent volume.

Although these auto-generated secrets are sufficient for most deployments, it is recommended to configure them manually using secret management for improved security and consistency.

Required variables:

ALTCHA_HMAC_SECRET
CODE_CHALLENGE_SECRET
EXOTDB_HMAC_SECRET
HASHING_SALT
JWT_SECRET
NODE_ID

If auto-generated secrets already exist, you’ll need to remove them from the /data/.env file—this file overrides any globally defined environment variables. You can delete the secrets directly from the file or use the Application UI to manage them.

Supported Variables

Security & Authentication

`ALTCHA_HMAC_SECRET`

Secret key used for ALTCHA HMAC operations such as challenge signing. Must be at least 24 characters long.

Default: auto-generated
Required: yes
Constraints: minimum length of 24 characters

`APP_IP_WHITELIST`

Restricts access to the application and administrative endpoints to a comma-separated list of whitelisted IP addresses or network masks.

Default: "" (no restrictions)
Example: "127.0.0.1/32,::1/128,fd00::/8" to allow only localhost

`CODE_CHALLENGE_SECRET`

Secret key used for signing code challenges during authentication flows. Must be at least 24 characters long.

Default: auto-generated
Required: yes
Constraints: minimum length of 24 characters

`JWT_ISSUER`

Issuer identifier used when generating JWT tokens.

Default: "ALTCHA_SENTINEL"
Optional

`JWT_SECRET`

Secret key used to sign JWT tokens. Must be at least 24 characters long.

Default: auto-generated
Required: yes
Constraints: minimum length of 24 characters

`JWT_TTL`

Time-to-live (TTL) for generated JWT tokens. Expressed in a human-readable duration format.

Default: "24h"
Format: e.g., "1h", "30m", "7d"

`PASSWORD_LOGIN_ENABLED`

Whether password-based login is enabled.

Default: "1"
Values: "1" = enabled, "0" = disabled

`PASSWORD_MIN_LENGTH`

The minimum length of the user-set passwords

Default: "8"
Values: Any integer

`LICENSE_KEY`

License key for the application. Used for commercial licensing purposes.

Default: empty string ("")
Optional

Networking & Access Control

`ACCESS_LOG_ANONYMIZE_IP_ADDRESS`

Whether to anonymize IP addresses in access logs.

Default: "1"
Values: "1" = yes, "0" = no

`ACCESS_LOG_ENABLED`

Whether access logging is enabled.

Default: "1"
Values: "1" = enabled, "0" = disabled

`ALLOWED_HOSTS`

Comma-separated list of allowed hostnames. Supports wildcards like *.example.com. If empty, all hosts are accepted.

Default: empty string ("")
Optional

`X_FORWARDED_FOR_TRUSTED`

Comma-separated list of trusted proxy IPs that are allowed to set the X-Forwarded-For header.

Default: empty string ("")
Optional

`BASE_URL`

Base URL used for generating absolute URLs within the application (e.g., for emails or redirects).

Default: empty string ("")
Optional

`HTTP2_CERT`

TLS certificate contents used to enable HTTP/2 support.

Default: empty string ("")
Optional

`HTTP2_KEY`

TLS certificate private key. Must be set together with HTTP2_CERT.

Default: empty string ("")
Optional

Caching

`CACHE_DURATION_API_KEYS`

How long to cache API keys before refreshing them.

Default: "10s"
Format: human-readable duration (e.g., "5m", "1h")

`CACHE_DURATION_TRAINING_DATA`

How long to cache training data before refreshing it.

Default: "1h"
Format: human-readable duration (e.g., "1d")

Database & Snapshots

`DATABASE_URL`

Database connection URL.

Default: "http://root:root@localhost:4080?bootstrap=1"
Optional

`EXOTDB_DATABASE_ADDR`

Address the embedded database server binds to.

Default: ":::4080"
Optional

`EXOTDB_DATABASE_LOCATION`

File path where the embedded database is stored.

Default: "./db/altcha-sentinel.db"
Optional

`EXOTDB_ENCRYPTION_KEY`

Encryption key for the embedded database.

Using this option is generally not recommended, as it may create obstacles for recovery and debugging. Instead, use the standard volume encryption mechanism, and utilize SNAPSHOTS_ENCRYPTION_KEY for database snapshot encryption.

Default: empty string ("")
Optional Constraints: minimum length of 24 characters

`EXOTDB_HMAC_SECRET`

HMAC secret for data signatures (mainly access-logs). Must be at least 24 characters long.

Default: empty string ("")
Optional
Constraints: minimum length of 24 characters

`EXOTDB_REDIS_ADDR`

Address the embedded Redis server binds to.

Default: ":::6389"
Optional

`EXOTDB_REDIS_LOCATION`

File path where the embedded Redis database is stored.

Default: "./db/redis.db"
Optional

`EXOTDB_ROOT_PASSWORD`

Root password for the embedded database.

Default: "root"
Optional

`SNAPSHOTS_CRON_SCHEDULE`

Cron schedule for automatic database snapshots. If empty, snapshotting is disabled.

Default: empty string ("")
Optional
Format: standard cron syntax (e.g., "0 2 * * *")

`SNAPSHOTS_DB_PREFIX`

Prefix path for storing database snapshots in storage.

Default: "altcha-sentinel-backups/db:${iso_date()}"
Optional
Note: ${iso_date()} will be replaced with the current date in ISO format

`SNAPSHOTS_ENCRYPTION_KEY`

Optional encryption key for database snapshots.

Default: ""
Optional

`SNAPSHOTS_STORAGE_PROVIDER`

Storage provider to use for snapshots.

Default: "local"
Values: "local", "azure", "s3"

`SNAPSHOTS_STORAGE_LOCAL_DIR`

Local directory where snapshots should be stored.

Default: "backups"
Optional

`SNAPSHOTS_STORAGE_AZURE_CONTAINER`

Azure container name for storing snapshots.

Default: empty string ("")
Optional

`SNAPSHOTS_STORAGE_AZURE_CONNECTION_STRING`

Azure connection string for snapshot storage.

Default: empty string ("")
Optional

`SNAPSHOTS_STORAGE_S3_BUCKET`

AWS S3 bucket name for storing snapshots.

Default: empty string ("")
Optional

`SNAPSHOTS_STORAGE_S3_ACCESS_KEY_ID`

AWS access key ID for S3 snapshot storage.

Default: empty string ("")
Optional

`SNAPSHOTS_STORAGE_S3_SECRET_ACCESS_KEY`

AWS secret access key for S3 snapshot storage.

Default: empty string ("")
Optional

`SNAPSHOTS_STORAGE_S3_REGION`

AWS region for S3 snapshot storage.

Default: empty string ("")
Optional

`SNAPSHOTS_STORAGE_S3_ENDPOINT`

Custom endpoint URL for S3-compatible storage (e.g., MinIO).

Default: empty string ("")
Optional

Redis

`REDIS_URL`

Redis connection URL.

Default: "redis://root:root@localhost:6389"
Optional

`REDIS_COMMAND_TIMEOUT`

Timeout for Redis commands in milliseconds.

Default: "1000"
Optional

`REDIS_CONNECT_TIMEOUT`

Timeout for Redis connections in milliseconds.

Default: "3000"
Optional

`REDIS_MAX_RETRIES`

Maximum number of retry attempts for Redis operations.

Default: "2"
Optional

`REDIS_KEY_PREFIX`

Prefix applied to all Redis keys.

Default: empty string ("")
Optional

Rate Limiting & Protection

`FLOOD_RATE_LIMIT`

Rate limit for flood protection, expressed as requests per duration (e.g., "100/1m").

Default: "100/1m"
Format: "requests/duration" (e.g., "50/30s")

`FLOOD_RATE_LIMIT_KEY`

Key used for rate limiting. Typically "ip".

Default: "ip"
Optional

Geolocation & Risk Detection

`HIGH_RISK_COUNTRIES_EXCLUDE`

Comma-separated list of country codes to exclude from high-risk classification. Refer to the Data Sources documentation for more details.

Default: empty string ("")
Optional
Example: "us,ru,il"

`IP_API_COM_TOKEN`

API token for the ip-api.com service, used for geolocation lookups.

Default: empty string ("")
Optional

`IPSTACK_COM_TOKEN`

API token for the ipstack.com service, used for geolocation lookups.

Default: empty string ("")
Optional

`IP_HEADERS_SECRET`

Secret used to validate incoming IP headers.

Default: empty string ("")
Optional

`FIREHOL_LEVEL1_URL`

URL to FireHOL Level 1 IP blocklist.

Default: "https://raw.githubusercontent.com/firehol/blocklist-ipsets/master/firehol_level1.netset"
Optional

`FIREHOL_TOR_EXITS_URL`

URL to FireHOL Tor exits IP blocklist.

Default: "https://raw.githubusercontent.com/firehol/blocklist-ipsets/master/tor_exits.ipset"
Optional

`FIREHOL_PROXIES_URL`

URL to FireHOL proxies IP blocklist.

Default: "https://raw.githubusercontent.com/firehol/blocklist-ipsets/master/firehol_proxies.netset"
Optional

`EMAIL_LIST_DISPOSABLE`

URL to a TXT file containing a list of disposable email domains.

Default: "https://raw.githubusercontent.com/disposable/disposable-email-domains/master/domains.txt"
Optional

Spam Handling

`DELETE_SPAM_SUBMISSIONS_IN`

Duration after which spam submissions are automatically deleted.

Default: "14d"
Format: human-readable duration (e.g., "7d", "24h")

Application Configuration

`CLUSTER_MODE`

Cluster operation mode. Can be "worker" or "node". Leave empty for single-instance deployment.

Default: empty string ("")
Values: "worker", "node", or empty

`DATA_DIR`

Directory where application data is stored.

Default: /data
Optional

`DEFAULT_ACCOUNT_NAME`

Name of the default account created on initial setup.

Default: "Default Account"
Optional

`DEFAULT_ROOT_PASSWORD`

Default root password for initial setup.

Default: "root"
Optional

`NODE_ID`

Unique identifier for this node in a cluster.

Default: auto-generated
Optional

`PORT`

Port the application listens on.

Default: "8080"
Optional

`TZ`

Application timezone. Defaults to system timezone.

Default: system timezone
Optional

Logging

`LOG_LEVEL`

Application log level.

Default: "info"
Values: "debug", "fatal", "error", "info", "silent", "trace", "warn"

`LOG_FORMAT`

Log output format.

Default: "json"
Values: "json" or "plain"

`REQUEST_LOGS_TTL`

Time-to-live for request logs.

Default: "72h"
Format: human-readable duration (e.g., "24h")

Monitoring

`MONITORING_HTTP_CREDENTIALS`

HTTP basic auth credentials for monitoring endpoints.

Default: empty string ("")
Optional

`MONITORING_IP_WHITELIST`

Comma-separated list of IP ranges allowed to access monitoring endpoints.

Default: "10.0.0.0/8,172.16.0.0/12,192.168.0.0/16,127.0.0.1/32,::1/128,fd00::/8,100.64.0.0/10"
Optional

Single Sign-On (SSO)

These variables accept configuration strings for their respective identity providers. The format depends on the provider.

`SSO_AZURE`

Azure OIDC SSO configuration.

Default: empty string ("")
Optional

`SSO_GOOGLE`

Google OIDC SSO configuration.

Default: empty string ("")
Optional

`SSO_KEYCLOAK`

Keycloak OIDC SSO configuration.

Default: empty string ("")
Optional

`SSO_LDAP`

LDAP SSO configuration.

Default: empty string ("")
Optional

`SSO_OKTA`

Okta OIDC SSO configuration.

Default: empty string ("")
Optional

SMTP / Email

`SMTP_URL`

URL for the SMTP server used to send outgoing emails.

Default: empty string ("")
Optional

File Storage

`STORAGE_PROVIDER`

Storage provider to use for file storage.

Default: "local"
Values: "local", "azure", "s3"

`STORAGE_LOCAL_DIR`

Local directory where uploaded files are stored.

Default: "uploads"
Optional

`STORAGE_AZURE_CONTAINER`

Azure container name for file storage.

Default: empty string ("")
Optional

`STORAGE_AZURE_CONNECTION_STRING`

Azure connection string for file storage.

Default: empty string ("")
Optional

`STORAGE_S3_BUCKET`

AWS S3 bucket name for file storage.

Default: empty string ("")
Optional

`STORAGE_S3_ACCESS_KEY_ID`

AWS access key ID for S3 file storage.

Default: empty string ("")
Optional

`STORAGE_S3_SECRET_ACCESS_KEY`

AWS secret access key for S3 file storage.

Default: empty string ("")
Optional

`STORAGE_S3_REGION`

AWS region for S3 file storage.

Default: empty string ("")
Optional

`STORAGE_S3_ENDPOINT`

Custom endpoint URL for S3-compatible file storage (e.g., MinIO).

Default: empty string ("")
Optional

Miscellaneous

`ANONYMIZE_IP_ADDRESS`

Whether to generally anonymize IP addresses.

Default: "1"
Values: "1" = yes, "0" = no

`INSPECT_ROUTE_ENABLED`

Whether the route GET /v1/inspect is enabled.

Default: "1"
Values: "1" = yes, "0" = no

`HASHING_SALT`

Random hashing salt used to IP and EDK hashing.

Let me know if you’d like this exported as Markdown, JSON, or HTML.

Required Variables

The following environment variables are required for the application to function:

ALTCHA_HMAC_SECRET
CODE_CHALLENGE_SECRET
JWT_SECRET
NODE_ID

For first-time setup, these will be automatically generated if not provided.