Skip to content

StelvioApp and stlv_app.py

Every Stelvio project has a stlv_app.py file at its root - this is where you create your Stelvio application. The Stelvio CLI automatically looks for this file in your current directory.

Minimal example

At its simplest, a stlv_app.py only needs a StelvioApp instance and an @app.run function:

from stelvio.app import StelvioApp
from stelvio.aws.function import Function

app = StelvioApp("my-app")


@app.run
def run() -> None:
    Function("process-user", handler="functions/users.process")

Warning

The app name is used to identify your infrastructure state. Changing it creates new resources rather than renaming existing ones. See State Management - Renaming for details.

Decorators

@app.run (required)

This is where you define your infrastructure components. It runs after configuration is loaded. All Stelvio components must be created inside this function (or in modules when using auto-discovery). See Project Structure for details on component creation order.

@app.config (optional)

For production use, you'll want to add an @app.config function. It configures Stelvio for your project and environment.

The function receives env: str - the environment name (e.g., "dev", "prod") and returns a StelvioAppConfig object. Stelvio calls it before any infrastructure is created.

Add it when you need to:

Warning

Without @app.config, only your personal environment (your username) is available. See Configuring environments.

Configuring AWS credentials and region

Stelvio follows the same credential resolution as the AWS CLI.

It looks at (in this order): - AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY env vars - AWS_PROFILE env var - The default profile in ~/.aws/credentials / ~/.aws/config

Profiles are entries in ~/.aws/config / ~/.aws/credentials. You can create them with aws configure, aws sso login, aws configure sso.

AWS region resolves in the same way. It uses AWS_REGION, AWS_DEFAULT_REGION or if none set it uses the selected profile's default.

Make sure AWS_PROFILE/AWS_REGION are environment variables

Use export AWS_PROFILE=my_profile. Check your environment variables by running env | grep AWS. Or for one command: AWS_PROFILE=my_profile stlv deploy. A bare AWS_PROFILE=my_profile on its own line only sets shell variable.

You can override this behaviour by using profile and region parameters of AwsConfig:

from stelvio.config import AwsConfig, StelvioAppConfig
from stelvio.app import StelvioApp

app = StelvioApp("my-app")


@app.config
def configuration(env: str) -> StelvioAppConfig:
    return StelvioAppConfig(
        aws=AwsConfig(profile="my-profile", region="eu-west-1")
    )


@app.run
def run() -> None:
    ...

Next Steps

Now that you understand the StelvioApp structure, you might want to explore: