Skip to content

Debug

Debug (atlas.debug) is the package containing the local debugging server script: server.py.

The local debug server is usually started from the Atlas API template's VS Code F5 configuration, through .atlas/debug.py. When it starts, it loads .atlas/.env.local and then builds the local Lambda layers before serving HTTP and WebSocket routes.

Local environment variables

To start the debug server, .atlas/.env.local must provide the AWS credentials, region and application name used by the project:

AWS_ACCESS_KEY_ID=...
AWS_SECRET_ACCESS_KEY=...
AWS_DEFAULT_REGION=sa-east-1
APP_NAME=MyApi

From APP_NAME, Atlas derives the application's environment parameter name using the same convention as the CDK deployment:

/atlas/<app-name-kebab>/environment

For example, APP_NAME=MyApi resolves to /atlas/my-api/environment. Atlas looks for that parameter in the AWS account associated with the configured credentials and region (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_DEFAULT_REGION).

If the application has already been deployed, the parameter contains its environment variables as an encrypted JSON document. The configured AWS credentials must have permission to read it. Atlas loads those values first and then applies the variables declared in .atlas/.env.local as a local overlay:

  • A declared value overrides a value with the same name from Parameter Store.
  • An undeclared or commented value continues to use the value from Parameter Store.
  • A variable declared with an empty value overrides the Parameter Store value with an empty string.

This makes it possible to keep optional local or mock values commented and enable only the overrides needed for a debugging session.

Before the first deployment, the parameter does not exist yet. In that case, declare every variable required to run the application locally in .atlas/.env.local. SSM_ENV_VARS_PARAMETER_NAME does not need to be declared for local debugging; it is an internal runtime value injected by CDK into deployed Lambda functions.

Server

Atlas local debug server.

This file should not be imported anywhere, except for inside the API's .atlas/debug.py file.

This module implements the local execution environment for Atlas APIs, faithfully simulating an AWS API Gateway + Lambda deployment for both REST and WebSocket interfaces.

It is designed exclusively for local development and debugging, allowing developers to run and test Atlas applications without deploying infrastructure via AWS CDK.

When executed, this server spins up:

An HTTP server
  • Binds to localhost:<port> (default: 8080)
  • Routes incoming HTTP requests to Lambda handlers defined under src/functions
  • Applies the same authorization logic used in production (custom authorizer)
  • Builds Lambda-compatible event payloads
  • Executes handlers in-process
A WebSocket server
  • Binds to localhost:<port + 1> (default: 8081)
  • Simulates API Gateway WebSocket lifecycle: $connect, message routing via channel.action, $disconnect
  • Executes Atlas WebSocket channels and actions like production
  • Persists connections in DynamoDB (ws_connections)
  • Validate public vs. private WebSocket rules
  • Token validation
  • Permission checks
  • Rate limiting
  • Idle TTL expiration
Notes
  • This script is strictly written to work with .atlas/debug.py in VSCode (F5 key).
  • Compared to a real deployment, some logics have been adapted as faithfully as possible, but may differ in several aspects.
  • Infrastructure settings (such as memory, SnapStart usage, rate/burst options and others) will not take effect in this local environment.
  • During debugging, some interactions with AWS may still be necessary (such as using the SSM parameter that stores environment variables, reading and writing DynamoDB tables, etc.).
  • Therefore, it's recommended to run this local debug server only after successfully deploying your application at least once.
Example 
# .atlas/debug.py

from atlas.debug import server

# Runs the debug server at the provided port. Use "use_local=True" if you are locally developing atlas-fw (editable) in a neighboring folder.
server.run_server(port=8080, use_local=True)