Configure HexCore with ServerConfig and LazyConfig

HexCore uses two classes to handle project configuration: ServerConfig, a Pydantic model that holds all runtime settings, and LazyConfig, a flexible loader that resolves which module to read from at startup. This page covers every field available on ServerConfig, explains how LazyConfig determines the active configuration, and shows how to write a config.py file in your project root.

ServerConfig

ServerConfig is a Pydantic BaseModel that groups all HexCore settings in one place. Create an instance of it in your config.py and override only the fields you need; everything else falls back to a sensible default.

config.py

from hexcore.config import ServerConfig

config = ServerConfig(
    host="0.0.0.0",
    port=8080,
    debug=False,
    sql_database_url="postgresql://user:pass@localhost/mydb",
    async_sql_database_url="postgresql+asyncpg://user:pass@localhost/mydb",
    repository_discovery_paths={
        "src.infrastructure.repositories",
        "src.infrastructure.repositories.implementations",
    },
)

Project settings

base_dir

Path

default:"Path('.')"

Root directory of the project. Used internally by the CLI when resolving relative paths.

Server settings

host

str

default:"\"localhost\""

Hostname the application server binds to.

port

int

default:"8000"

Port the application server listens on.

debug

bool

default:"True"

Enables debug mode. Set to False for production deployments.

SQL database settings

sql_database_url

str

default:"\"sqlite:///./db.sqlite3\""

Synchronous SQLAlchemy connection URL. Used by Alembic and any sync ORM sessions.

async_sql_database_url

str

default:"\"sqlite+aiosqlite:///./db.sqlite3\""

Asynchronous SQLAlchemy connection URL. Used for async database sessions throughout HexCore’s infrastructure layer.

MongoDB settings

mongo_database_url

str

default:"\"mongodb://localhost:27017\""

Synchronous MongoDB connection URL.

async_mongo_database_url

str

default:"\"mongodb+async://localhost:27017\""

Async MongoDB connection URL used by the Beanie ODM layer.

mongo_db_name

str

default:"\"euphoria_db\""

Name of the MongoDB database to connect to.

mongo_uri

str

default:"\"mongodb://localhost:27017/euphoria_db\""

Full MongoDB URI including the database name. Useful for drivers that accept a combined connection string.

Redis settings

redis_uri

str

default:"\"redis://localhost:6379/0\""

Full Redis connection URI used by the cache and event bus backends.

redis_host

str

default:"\"localhost\""

Redis server hostname.

redis_port

int

default:"6379"

Redis server port.

redis_db

int

default:"0"

Redis logical database index.

redis_cache_duration

int

default:"300"

Default TTL in seconds for cached values written by HexCore’s cache layer.

Cache settings

cache_backend

ICache

default:"MemoryCache()"

Active cache implementation. Must be an instance (or subclass instance) of ICache. Swap in RedisCache() or your own implementation for production.

CORS / security settings

allow_origins

list[str]

default:"[\"*\"]"

List of allowed CORS origins. Defaults to ["*"] when debug=True.

allow_credentials

bool

default:"True"

Whether to allow cookies and credentials in CORS requests.

allow_methods

list[str]

default:"[\"*\"]"

HTTP methods allowed in CORS requests.

allow_headers

list[str]

default:"[\"*\"]"

HTTP headers allowed in CORS requests.

Event bus

event_bus

EventBus

default:"InMemoryEventBus()"

The active EventBus implementation. Defaults to an in-process, in-memory bus. Replace with RedisEventBus, PostgresEventBus, or any custom EventBus subclass for distributed setups.

event_dispatcher is deprecated. The old event_dispatcher field is an alias for event_bus kept for backwards compatibility. It emits a DeprecationWarning when accessed. Update any existing configs to use event_bus instead.

Repository discovery

repository_discovery_paths

set[str]

default:"set()"

Python module paths HexCore scans when auto-wiring repositories into the Unit of Work. Each entry must be a dotted module path (e.g. "src.infrastructure.repositories").

v2 breaking change. In HexCore v2, repository discovery is fully explicit. If repository_discovery_paths is left empty, no repository modules are auto-loaded and the Unit of Work will raise an explicit error rather than silently failing. Always set this field in your config.py.

CQRS

cqrs

CQRSConfig | None

default:"None"

Optional CQRS configuration object (hexcore.application.cqrs.config.CQRSConfig). When None, CQRS is disabled and has no impact on existing modules.

LazyConfig

LazyConfig is the configuration loader HexCore uses internally everywhere it needs settings — in the Unit of Work, in BaseDomainService, and in CLI commands. It caches the resolved ServerConfig instance after the first load, so there is no repeated import overhead.

Resolution priority

LazyConfig.get_config() walks through candidate module sources in this order and returns the first valid ServerConfig it finds:

HEXCORE_CONFIG_MODULE env var

If the HEXCORE_CONFIG_MODULE environment variable is set to a dotted module path (e.g. myapp.settings), that module is imported first. HexCore looks for either a config attribute that is a ServerConfig instance or a ServerConfig subclass defined in the module.

export HEXCORE_CONFIG_MODULE=myapp.settings

HEXCORE_CONFIG_MODULES env var

If HEXCORE_CONFIG_MODULES is set, it is split on commas and each entry is tried in order.

export HEXCORE_CONFIG_MODULES=myapp.settings,myapp.settings_override

LazyConfig.set_config_modules(...)

You can provide module candidates programmatically — useful for testing or multi-tenant setups — by calling set_config_modules before the first get_config() call.

from hexcore.config import LazyConfig

LazyConfig.set_config_modules(["myapp.settings", "myapp.overrides"])

Calling set_config_modules also clears the cached instance, so the next get_config() re-resolves from scratch.

Default: config module in project root

If none of the above sources yield a valid config, LazyConfig falls back to importing the bare config module — that is, a config.py file at the root of your project (wherever Python’s module search path starts).

Attribute lookup inside a module

Within each candidate module, LazyConfig looks for:

A module-level attribute named config that is a ServerConfig instance. If the attribute is a ServerConfig subclass (not yet instantiated), it will be instantiated automatically.
A module-level class named ServerConfig that is a subclass of hexcore.config.ServerConfig.

If neither is found, the module is skipped and the next candidate is tried. When all candidates are exhausted, LazyConfig falls back to a default ServerConfig() with no custom settings.

Clearing the cache

from hexcore.config import LazyConfig

# Force re-resolution on next get_config() call
LazyConfig.clear_cache()

Writing a config.py

Place a config.py in your project root (or wherever Python resolves the config module). The hexcore init command generates this file automatically; the example below shows what it produces for the hexagonal template.

config.py

from hexcore.config import ServerConfig

config = ServerConfig(
    repository_discovery_paths={
        "src.infrastructure.repositories",
        "src.infrastructure.repositories.implementations",
    }
)

For a production configuration with a real database and Redis cache:

config.py

from hexcore.config import ServerConfig
from hexcore.infrastructure.cache.cache_backends.redis import RedisCache

config = ServerConfig(
    debug=False,
    host="0.0.0.0",
    port=8000,

    # SQL
    sql_database_url="postgresql://user:secret@db-host/prod",
    async_sql_database_url="postgresql+asyncpg://user:secret@db-host/prod",

    # Redis
    redis_uri="redis://redis-host:6379/0",
    cache_backend=RedisCache(),
    redis_cache_duration=600,

    # Repository discovery
    repository_discovery_paths={
        "src.infrastructure.repositories",
    },
)

Set the HEXCORE_CONFIG_MODULE environment variable in your deployment environment (Docker, systemd, etc.) to point at your production config module without changing any source files. This keeps secrets out of version control.

Get Started

Core Concepts

Configuration

Domain Layer

CQRS & Messaging

Infrastructure

CLI Reference

Configure HexCore with ServerConfig and LazyConfig

ServerConfig

Project settings

Server settings

SQL database settings

MongoDB settings

Redis settings

Cache settings

CORS / security settings

Event bus

Repository discovery

CQRS

LazyConfig

Resolution priority

Attribute lookup inside a module

Clearing the cache

Writing a config.py

Build docs developers (and LLMs) love

Get Started

Core Concepts

Configuration

Domain Layer

CQRS & Messaging

Infrastructure

CLI Reference

Documentation Index

​ServerConfig

​Project settings

​Server settings

​SQL database settings

​MongoDB settings

​Redis settings

​Cache settings

​CORS / security settings

​Event bus

​Repository discovery

​CQRS

​LazyConfig

​Resolution priority

​Attribute lookup inside a module

​Clearing the cache

​Writing a config.py

Build docs developers (and LLMs) love

ServerConfig

Project settings

Server settings

SQL database settings

MongoDB settings

Redis settings

Cache settings

CORS / security settings

Event bus

Repository discovery

CQRS

LazyConfig

Resolution priority

Attribute lookup inside a module

Clearing the cache

Writing a config.py