App Config & Lifecycle

An App Config is the entry point that wires an application into the AMSDAL framework. The same mechanism powers both your own application (app.py) and reusable contrib plugins (auth, frontend configs, storages, …).

Subclass AppConfig and implement the lifecycle hooks you need:

from amsdal.contrib.app_config import AppConfig


class MainAppConfig(AppConfig):
    def on_setup(self) -> None:
        # Register the app's wiring before the framework starts (see below).
        ...

The class is referenced by the APP_CONFIG setting (default app.MainAppConfig). Contrib plugins are listed in CONTRIBS. See Configuration.

Lifecycle hooks

Hook	When it runs	Framework state	Use it for
on_setup (optional)	Start of AmsdalManager.setup(), before models and connections	Not operational — no DB/model access	Register event listeners, declare permissions, register response models, register services
on_ready (optional)	End of AmsdalManager.setup(), after models and connections	Fully operational — ORM/connections usable	Seed/ensure initial data, warm caches, start background jobs, run health checks
on_teardown (optional)	Start of AmsdalManager.teardown(), before resources are released	Still operational	Close external clients, flush buffers, stop jobs, release resources

Ordering

• on_setup and on_ready run contrib apps first, then your app.
• on_teardown runs in reverse: your app first, then contrib apps.
• The same instance receives all three hooks, so state stored on self in on_setup is available in on_ready and on_teardown.

on_setup

Runs early, before models are loaded and before any connection is opened. Keep it to registration/wiring only — do not query the database or instantiate models.

def on_setup(self) -> None:
    from amsdal_utils.events import EventBus
    from amsdal_server.apps.common.events.server import ServerStartupEvent

    from app.event_handlers import MyStartupListener

    EventBus.subscribe(ServerStartupEvent, MyStartupListener)

on_ready

Runs once the framework is fully set up (manager.is_setup is True). The ORM and connections are available, so this is where startup data work belongs.

def on_ready(self) -> None:
    from models.settings import AppSettings

    if not AppSettings.objects.count().execute():
        AppSettings(initialized=True).save()

on_teardown

Runs at the start of teardown, while connections are still alive. Use it to undo what the app set up.

def on_teardown(self) -> None:
    self._external_client.close()

When do hooks run?

Hooks run as part of the running application — on_setup/on_ready when it starts, on_teardown when it stops. Building the app (amsdal build) does not run any hook. That means on_setup can safely import generated code such as your transactions.* modules: by the time hooks run, the app has already been built.