Environment Variables

Blocklet Server uses environment variables for detailed configuration of its behavior, from network ports to security settings. This approach provides a flexible way to customize your server instance for different environments (development, staging, production) without altering configuration files.

All server-specific variables are prefixed with ABT_NODE_.

Configuration Priority#

Environment variables have the highest precedence in the configuration hierarchy. The server applies settings in the following order, with later sources overwriting earlier ones:

1. Default values
2. Configuration file (config.yml)
3. Environment variables (ABT_NODE_*)

Server Configuration Variables#

The following tables provide a comprehensive reference for all ABT_NODE_ environment variables that you can use to customize the server.

Network and Ports#

These variables control the network bindings and ports used by the Blocklet Server and its components.

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

Authentication and Security#

Manage access control, session settings, and cryptographic keys. Variables marked as system-generated should not be set manually.

Variable	Purpose	Default / Status	Example
ABT_NODE_DID	Decentralized Identifier for the server instance	System-generated	z1mu...
ABT_NODE_PK	Public key for the server's DID	System-generated	0x04abc...
ABT_NODE_SK	Secret key for the server's DID. Keep secure.	System-generated	0xdef456...
ABT_NODE_SESSION_SECRET	Secret key for session encryption	System-generated	random-secret
ABT_NODE_TOKEN_SECRET	Secret key for JWT token signing	System-generated	jwt-secret
ABT_NODE_SESSION_TTL	Session time-to-live in seconds	3600	7200
ABT_NODE_SESSION_CACHE_TTL	Session cache time-to-live in seconds	300	600
ABT_NODE_ADMIN_PATH	Path prefix for the admin dashboard	/.well-known/service/admin	/admin
ABT_NODE_IP_WHITELIST	Comma-separated list of IPs allowed to access admin	(all IPs allowed)	127.0.0.1,192.168.1.0/24
ABT_NODE_DOMAIN_WHITELIST	Comma-separated list of domains allowed for CORS	(none)	example.com,*.example.com
ABT_NODE_DOMAIN_BLACKLIST	Comma-separated list of domains to block	(none)	malicious.com
ABT_NODE_DOMAIN_WHITELIST_HEADERS	Additional headers for CORS whitelist responses	(none)	X-Custom-Header
ABT_NODE_NO_PASSKEY_USER_VERIFY	Disable passkey user verification (1: disable, 0: enable)	0	1

Database and Storage#

Configure the primary database and caching layer.

Variable	Purpose	Default	Example
ABT_NODE_POSTGRES_URL	PostgreSQL connection URL. If not set, SQLite is used.	(uses SQLite)	postgresql://user:pass@host:5432/dbname
ABT_NODE_CACHE_REDIS_URL	Redis connection URL for caching. If not set, in-memory cache is used.	(in-memory cache)	redis://localhost:6379
ABT_NODE_CACHE_SQLITE_PATH	Path to SQLite cache database file	{DATA_DIR}/core/db-cache.db	/tmp/cache.db
ABT_NODE_NO_CACHE	Disable caching entirely (1: disable, 0: enable)	0	1
ABT_NODE_IGNORE_USE_POSTGRES	Force use of SQLite even if PostgreSQL is configured (1: force SQLite)	0	1
ABT_NODE_SQLITE_LARGE_CACHE	Enable large cache for SQLite (1: enable)	0	1

Docker Configuration#

Set default resource limits and behavior for blocklets running in Docker containers.

Variable	Purpose	Default	Example
ABT_NODE_NOT_ALLOW_DOCKER	Disable Docker support entirely (1: disable, 0: enable)	0	1
ABT_NODE_DOCKER_MEMORY	Default memory limit for Docker containers	512m	1g
ABT_NODE_DOCKER_CPUS	Default CPU limit for Docker containers	1	2
ABT_NODE_DOCKER_DISK_SIZE	Default disk size limit for Docker containers	10g	20g
ABT_NODE_SKIP_DOCKER_CHOWN	Skip chown operations in Docker containers (1: skip)	0	1

Logging and Debugging#

Control logging levels, locations, and enable development modes.

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

Performance and Limits#

Tune server performance and set operational limits.

Variable	Purpose	Default	Example
ABT_NODE_MAX_CLUSTER_SIZE	Maximum number of cluster instances	4	8
ABT_NODE_JOB_BACKOFF_SECONDS	Backoff time for job scheduling in seconds	600	300
ABT_NODE_EMAIL_RATE_LIMIT	Rate limit for email operations (per minute)	10	5
ABT_NODE_ENSURE_RUNNING_CHECK_INTERVAL	Interval for checking running blocklets (ms)	30000	60000
ABT_NODE_ENSURE_RUNNING_HIGH_LOAD_CPU	CPU threshold (%) for high load detection	80	90
ABT_NODE_ENSURE_RUNNING_HIGH_LOAD_MEMORY	Memory threshold (%) for high load detection	80	85
ABT_NODE_ENSURE_RUNNING_HIGH_LOAD_DISK	Disk threshold (%) for high load detection	90	95
ABT_NODE_ENABLE_ENSURE_BLOCKLET_RUNNING	Enable automatic blocklet running assurance (1: enable)	1	0

Domain and Routing#

Configure how the server handles domains, routing, and certificates.

Variable	Purpose	Default	Example
ABT_NODE_DID_DOMAIN	Domain for DID-based routing	Auto-detected	did.example.com
ABT_NODE_DASHBOARD_DOMAIN	Domain for admin dashboard	Auto-detected	dashboard.example.com
ABT_NODE_ROUTER_PROVIDER	Router provider implementation (nginx, nodejs)	nginx	nodejs
ABT_NODE_ENABLE_IPV6	Enable IPv6 support (1: enable, 0: disable)	0	1
ABT_NODE_FORCE_INTRANET	Force intranet mode (1: enable, 0: disable)	0	1
ABT_NODE_WILDCARD_CERT_HOST	Host for downloading wildcard certificates	https://releases.arcblock.io/certs	https://custom-cert-host.com

External Services#

Configure endpoints for external services like the web wallet and DID registry.

Variable	Purpose	Default	Example
ABT_NODE_WEB_WALLET_URL	URL for the web wallet service	https://web.abtnetwork.io	https://custom-wallet.com
ABT_NODE_DID_REGISTRY	DID registry endpoint	https://registry.arcblock.io	https://custom-registry.com

System Generated Variables#

These variables are set internally by the system for its own operational purposes. You should not set these manually.

Variable	Purpose
ABT_NODE_BINARY_NAME	Name of the CLI binary
ABT_NODE_COMMAND_NAME	Name of the CLI command
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_BLOCKLET_MODE	Current blocklet mode
ABT_NODE_KERNEL_MODE	Current kernel mode

Blocklet-Specific Environments#

In addition to server-wide configuration, individual blocklets can define their own required environment variables in their blocklet.yml meta file.

When developing a blocklet locally, you can provide values for these variables by creating a .env file in the blocklet's root directory. The CLI (blocklet dev) will automatically load these files and prompt you for any required variables that are still missing.

Security Considerations#

• Use strong, randomly generated values for secret keys and other sensitive variables.
• Limit access to the server environment and any files where these variables are stored.
• Consider using a secrets management tool for production deployments to securely inject environment variables.