Environment Variables

Environment variables provide a powerful way to configure Blocklet Server and the blocklets it runs. They override default settings and values from configuration files, making them ideal for tailoring your setup across different environments like development, staging, and production.

Configuration Priority

Blocklet Server applies settings in a specific order of precedence, with later sources overriding earlier ones:

Default Values
The built-in default settings for the server.
Configuration File
Settings defined in your config.yml file.
Environment Variables
The highest priority. Any ABT_NODE_* variable you set will take precedence over the other sources.

Blocklet-Specific Environments

Individual blocklets can define their own required environment variables in their blocklet.yml manifest. When you run a blocklet in development mode (e.g., using blocklet dev), you can provide these variables by creating a .env file in the blocklet's root directory.

Blocklet Server uses dotenv-flow to load these files, which means you can use a cascade of files like .env, .env.development, and .env.local to manage environment-specific configurations. If any required variables are missing when you start the blocklet, the CLI will prompt you to enter them.

Blocklet Server Environment Variables

All environment variables that control the core Blocklet Server daemon are prefixed with ABT_NODE_. The following sections provide a comprehensive reference for these variables, grouped by category.

Network and Ports

These variables configure the network interfaces and ports that Blocklet Server and its components use.

Variable	Purpose	Default
`ABT_NODE_PORT`	Main port where the Blocklet Server daemon listens.	`8089`
`ABT_NODE_SERVICE_PORT`	Port for internal service communication.	`40404`
`ABT_NODE_BLOCKLET_PORT`	Starting port for blocklet applications.	`8090`
`ABT_NODE_HTTP_PORT`	HTTP port for the gateway/router.	`80`
`ABT_NODE_HTTPS_PORT`	HTTPS port for the gateway/router.	`443`
`ABT_NODE_ROUTER_HTTP_PORT`	HTTP port specifically for the router provider.	Same as `ABT_NODE_HTTP_PORT`
`ABT_NODE_ROUTER_HTTPS_PORT`	HTTPS port specifically for the router provider.	Same as `ABT_NODE_HTTPS_PORT`
`ABT_NODE_UPDATER_PORT`	Port for the updater service.	`40405`
`ABT_NODE_EVENT_PORT`	Port for event hub communication.	`40407`
`ABT_NODE_HOST`	Host address for the server to bind to.	`0.0.0.0`

Authentication and Security

Manage access control, sessions, DIDs, and security policies.

Variable	Purpose	Default / Notes
`ABT_NODE_DID`	Decentralized Identifier for the server instance.	System-generated
`ABT_NODE_PK`	Public key for the server's DID.	System-generated
`ABT_NODE_SK`	Secret key for the server's DID.	System-generated (keep secure)
`ABT_NODE_SESSION_SECRET`	Secret key for session encryption.	System-generated
`ABT_NODE_TOKEN_SECRET`	Secret key for JWT token signing.	System-generated
`ABT_NODE_SESSION_TTL`	Session time-to-live in seconds.	`3600` (1 hour)
`ABT_NODE_SESSION_CACHE_TTL`	Session cache time-to-live in seconds.	`300` (5 minutes)
`ABT_NODE_ADMIN_PATH`	Path prefix for the admin dashboard.	`/.well-known/service/admin`
`ABT_NODE_IP_WHITELIST`	Comma-separated list of IP addresses allowed to access admin.	None (all IPs allowed)
`ABT_NODE_DOMAIN_WHITELIST`	Comma-separated list of domains allowed for CORS.	None
`ABT_NODE_DOMAIN_BLACKLIST`	Comma-separated list of domains to block.	None
`ABT_NODE_DOMAIN_WHITELIST_HEADERS`	Additional headers to include in CORS whitelist responses.	None
`ABT_NODE_NO_PASSKEY_USER_VERIFY`	Disable passkey user verification. Set to `1` to disable.	`0` (enabled)

Database and Storage

Configure database connections and caching mechanisms.

Variable	Purpose	Default / Notes
`ABT_NODE_POSTGRES_URL`	PostgreSQL connection URL.	Uses SQLite if not specified.
`ABT_NODE_CACHE_SQLITE_PATH`	Path to SQLite cache database file.	`{DATA_DIR}/core/db-cache.db`
`ABT_NODE_CACHE_REDIS_URL`	Redis connection URL for caching.	None (uses in-memory cache)
`ABT_NODE_SQLITE_LARGE_CACHE`	Enable large cache for SQLite. Set to `1` to enable.	`0` (disabled)
`ABT_NODE_NO_CACHE`	Disable caching entirely. Set to `1` to disable.	`0` (enabled)
`ABT_NODE_IGNORE_USE_POSTGRES`	Force use of SQLite even if PostgreSQL is configured. Set to `1`.	`0`
`ABT_NODE_IGNORE_RESTART_POSTGRES`	Skip restarting PostgreSQL during startup. Set to `1`.	`0`

Docker Configuration

Customize the behavior of blocklets that run in Docker containers.

Variable	Purpose	Default
`ABT_NODE_NOT_ALLOW_DOCKER`	Disable Docker support entirely. Set to `1` to disable.	`0` (enabled)
`ABT_NODE_DOCKER_MEMORY`	Default memory limit for Docker containers.	`512m`
`ABT_NODE_DOCKER_CPUS`	Default CPU limit for Docker containers.	`1`
`ABT_NODE_DOCKER_DISK_SIZE`	Default disk size limit for Docker containers.	`10g`
`ABT_NODE_SKIP_DOCKER_CHOWN`	Skip chown operations in Docker containers. Set to `1` to skip.	`0`
`ABT_NODE_TEST_DOCKER`	Enable Docker testing mode. Set to `1` to enable.	`0`

Logging and Debugging

Control logging levels, locations, and enable debugging modes.

Variable	Purpose	Default / Values
`ABT_NODE_LOG_DIR`	Directory for log files.	`{DATA_DIR}/logs/_abtnode`
`ABT_NODE_LOG_NAME`	Name of the log file.	`daemon`
`ABT_NODE_LOG_LEVEL`	Logging level.	`info` (Values: `error`, `warn`, `info`, `debug`)
`ABT_NODE_DEBUG_AS_SERVERLESS`	Enable serverless debugging mode. Set to `1` to enable.	`0`
`ABT_NODE_DEV_MODE`	Enable development mode with additional debugging. Set to `1` to enable.	`0`

Performance and Limits

Tune performance parameters and set operational limits.

Variable	Purpose	Default
`ABT_NODE_MAX_CLUSTER_SIZE`	Maximum number of cluster instances.	`4`
`ABT_NODE_JOB_BACKOFF_SECONDS`	Backoff time for job scheduling in seconds.	`600` (10 minutes)
`ABT_NODE_BLACKLIST_REFRESH_INTERVAL`	Interval for refreshing blacklist in minutes.	`2`
`ABT_NODE_EMAIL_RATE_LIMIT`	Rate limit for email operations per minute.	`10`
`ABT_NODE_EMAIL_VERIFY_RATE_LIMIT`	Rate limit for email verification per minute.	`5`
`ABT_NODE_ENSURE_RUNNING_CHECK_INTERVAL`	Interval for checking running blocklets in milliseconds.	`30000` (30 seconds)
`ABT_NODE_ENSURE_RUNNING_HIGH_LOAD_CPU`	CPU threshold (%) for high load detection.	`80`
`ABT_NODE_ENSURE_RUNNING_HIGH_LOAD_MEMORY`	Memory threshold (%) for high load detection.	`80`
`ABT_NODE_ENSURE_RUNNING_HIGH_LOAD_DISK`	Disk threshold (%) for high load detection.	`90`
`ABT_NODE_ENABLE_ENSURE_BLOCKLET_RUNNING`	Enable automatic blocklet running assurance. Set `0` to disable.	`1`

Domain and Routing

Configure how Blocklet Server handles domains, certificates, and routing.

Variable	Purpose	Default / Values
`ABT_NODE_DID_DOMAIN`	Domain for DID-based routing.	Auto-detected
`ABT_NODE_SLP_DOMAIN`	Domain for SLP (Service Location Protocol).	Auto-detected
`ABT_NODE_DASHBOARD_DOMAIN`	Domain for the admin dashboard.	Auto-detected
`ABT_NODE_WILDCARD_CERT_HOST`	Host for downloading wildcard certificates.	`https://releases.arcblock.io/certs`
`ABT_NODE_ENABLE_SLP_DOMAIN`	Enable SLP domain support. Set to `1` to enable.	`0`
`ABT_NODE_ENABLE_IPV6`	Enable IPv6 support. Set to `1` to enable.	`0`
`ABT_NODE_FORCE_INTRANET`	Force intranet mode. Set to `1` to enable.	`0`
`ABT_NODE_ROUTER_PROVIDER`	Router provider implementation.	`nginx` (Values: `nginx`, `nodejs`)
`ABT_NODE_ROUTER_CONFIG`	Path to an additional router configuration file.	None

External Services

Configure endpoints for external services that Blocklet Server interacts with.

Variable	Purpose	Default
`ABT_NODE_WEB_WALLET_URL`	URL for the web wallet service.	`https://web.abtnetwork.io`
`ABT_NODE_DID_REGISTRY`	DID registry endpoint.	`https://registry.arcblock.io`
`ABT_NODE_LAUNCHER_DID`	DID of the launcher service.	Auto-configured
`ABT_NODE_BLOCKLET_LAUNCHER_URL`	Address for node registration.	Auto-detected
`ABT_NODE_EVENT_HOSTNAME`	Hostname for the event hub.	`localhost`

Development and Testing

Variables primarily used for development, testing, and debugging purposes.

Variable	Purpose	Default / Notes
`ABT_NODE_SKIP_VERSION_CHECK`	Skip version compatibility checks. Set to `1` to skip.	`0`
`ABT_NODE_TEST_DNS_SERVER`	DNS server for testing.	None
`ABT_NODE_TEST_MIN_CONSECUTIVE_TIME`	Minimum consecutive time for test runs in milliseconds.	`1000`
`ABT_NODE_MOCK_DID_NAMES`	Mock DID names for testing (comma-separated).	None
`ABT_NODE_FAKE_DISK_INFO`	Use fake disk information for testing. Set to `1` to enable.	`0`

System-Generated Variables

These variables are set automatically by the system at runtime. You should not configure them manually as their values are derived from the system's state and context.

Variable	Purpose
`ABT_NODE_BINARY_NAME`	Name of the CLI binary.
`ABT_NODE_COMMAND_NAME`	Name of the CLI command being executed.
`ABT_NODE_PACKAGE_NAME`	NPM package name for the server.
`ABT_NODE_VERSION`	Version of the Blocklet Server.
`ABT_NODE_RESTART_RUNNING_COMPONENT`	Flag indicating component restart status.
`ABT_NODE_OWNER_NFT_HOLDER`	NFT holder information for ownership.
`ABT_NODE_OWNER_NFT_ISSUER`	NFT issuer information for ownership.
`ABT_NODE_BLOCKLET_MODE`	Current blocklet mode.
`ABT_NODE_KERNEL_MODE`	Current kernel mode.

Security Considerations

When configuring your Blocklet Server, keep the following security best practices in mind:

Secure Secrets: Always use strong, randomly generated values for secret keys like ABT_NODE_SESSION_SECRET and ABT_NODE_SK.
Limit Access: Restrict file system access to the data directory and any configuration files to authorized users only.
Use Management Tools: For production deployments, consider using a dedicated tool for managing environment variables to avoid exposing secrets in shell history or plain text files.