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:

  1. Default Values: The built-in default settings for the server.
  2. Configuration File: Settings defined in your config.yml file.
  3. 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.
blocklet