Setup procedure

Deploy and verify an application

This procedure connects an AWS account, validates an application repository, creates an Astroscale app, and verifies the resulting CloudFormation stack, image deployment, DNS record, and HTTPS endpoint.

Start with requirements All console procedures Runtime operations

01 / REQUIREMENTS

Collect the required account and repository information.

Do not start CloudFormation onboarding until every applicable item below is available.

Item	Required value or state	Where to verify it
Astroscale access	An organization user with permission to manage AWS accounts and create apps.	Console → Settings → Members
AWS access	Permission to create CloudFormation and IAM resources in the target AWS account.	AWS IAM and CloudFormation consoles
GitHub source connection	A GitHub CodeConnection in status `Available` in the same AWS account and Region as the app.	AWS Developer Tools → Settings → Connections
Repository	A GitHub repository readable through the selected CodeConnection.	GitHub repository settings and CodeConnection authorization
Container contract	A root-level Linux/amd64 `Dockerfile`; non-root runtime; read-only filesystem compatibility; HTTP listener on the configured port.	Repository root and local container test
Hostname	An unused `*.astroscale.dev` subdomain or a verified customer Route 53 domain.	Console → Domains and AWS Route 53

02 / REPOSITORY VALIDATION

Test the same container contract used by CodeBuild.

Astroscale builds only the repository root. Compose files, alternate Dockerfile paths, and Docker build arguments are not used.

01
Confirm the Dockerfile location
Verify that the file is named Dockerfile and is committed at the repository root. Confirm the selected Git branch contains it.
02
Build for the required architecture
From the repository root, run the command below. Replace APP_IMAGE with a local tag.
```
docker build --platform linux/amd64 -t APP_IMAGE .
```
03
Run with production restrictions
Replace 8080 if the application uses another port. The container must start as UID/GID 65534 with a read-only root filesystem and all Linux capabilities removed.
```
docker run --rm --read-only --cap-drop ALL \
  --user 65534:65534 -p 127.0.0.1:8080:8080 APP_IMAGE
```
04
Verify the listener and health response
In another terminal, request the root path. Continue only if it returns an HTTP 2xx response.
```
curl --fail --show-error http://127.0.0.1:8080/
```
05
Commit the tested files
Push the Dockerfile and application changes to the exact branch or commit that will be selected in Astroscale.

03 / AWS ACCOUNT CONNECTION

Create the scoped deployer role with CloudFormation.

Astroscale assumes a role protected by an external ID. It does not collect an AWS access key or secret access key.

01
Create and authorize the GitHub connection
In the target AWS Region, open Developer Tools → Settings → Connections. Create a GitHub connection, complete GitHub browser authorization, and wait for status Available.
02
Generate onboarding parameters
In Astroscale, open AWS accounts. Enter the available CodeConnection ARN and select Generate onboarding. Confirm that the displayed AWS account and Region are the intended deployment target.
03
Open AWS Quick Create
Select Open AWS Quick Create while signed into the target AWS account. Review the template, acknowledge named IAM resources, and create the stack. Do not change the supplied external ID.
04
Wait for a terminal stack state
In AWS CloudFormation, wait for CREATE_COMPLETE. If the stack enters a rollback state, open Events, correct the first failed resource, and create a new onboarding session before retrying.
05
Verify the connected account
Return to Astroscale. Confirm that the account shows its 12-digit AWS account ID, deployer role ARN, enabled Region, and available source connection.

04 / APPLICATION CREATION

Create the app and wait for the first immutable image.

The initial operation creates regional prerequisites, the app CloudFormation stack, ECR repository, CodeBuild project, DNS record, and first Git-SHA image deployment.

01
Open Fleet → Provision app
Select the connected AWS account and the Region that contains the available CodeConnection.
02
Enter source and runtime settings
Enter the repository URL, branch, container port, compute size, placement, and hostname. The port must match the listener tested in the repository procedure.
03
Review optional infrastructure
Enable Reserved IP only when a stable IPv4 address is required. Enable PostgreSQL only when the app is ready to consume the protected DATABASE_URL injected by Astroscale.
04
Create the application
Select Create. The app progresses through creating, bootstrapping, and deployment states. Do not submit a second infrastructure action while it is transitioning.
05
Wait for the deployment result
Open the app and inspect Deployment history. A successful deployment records the immutable Git SHA and ECR image URI before the app becomes running.

05 / VERIFICATION

Check control-plane, AWS, DNS, and HTTP state.

All checks below must agree. A healthy CloudFormation stack does not prove that the application process is serving traffic.

01
Verify Astroscale state
Confirm app status running, deployment status succeeded, and no current status reason. Confirm the image tag matches the expected Git commit.
02
Verify CloudFormation
In the app's AWS Region, open CloudFormation and locate the stack name shown on the app page. Confirm CREATE_COMPLETE or UPDATE_COMPLETE.
03
Verify DNS
Resolve the app hostname and confirm it returns an address managed by the current app or shared host.
```
dig +short APP_HOSTNAME
```
04
Verify HTTPS
Request the public root path and require a 2xx response.
```
curl --fail --show-error --silent https://APP_HOSTNAME/
```
05
Inspect container logs
Select Tail logs. Confirm that the process remains running, listens on the configured port, and does not report missing runtime configuration.

06 / FAILURE RECOVERY

Use the first failing system to choose the repair.

Wait for the current AWS operation to reach a terminal state before retrying or starting a repair.

Observed result	Check	Next action
CodeBuild cannot start	App page CodeBuild project name and Region; AWS CodeBuild project existence.	Use Repair regional build infrastructure. Do not change the app Region to work around a stale project ARN.
CloudFormation rollback	The first failed logical resource in CloudFormation Events.	Correct the reported permission, quota, naming conflict, or existing-resource conflict. Retry only after rollback completes.
Image build failure	Deployment build log.	Correct the Dockerfile or source. For Docker Hub HTTP 429, wait for the registry pull window; do not add credentials to the Dockerfile.
Health check failure	Container logs, listener address, configured port, and `/` response.	Bind to `0.0.0.0:PORT`, return 2xx from `/`, then redeploy.
DNS or TLS failure	Route 53 record, current app address, and certificate issuance state.	Wait for DNS propagation when the record is correct. Do not overwrite an unrelated record.
Old regional stack remains after repair	App Source panel and change history.	After verifying the replacement app, select Clean up old regional infrastructure. This deletes only the recorded superseded app stack.

Account, app, domain, and access procedures Deployment, environment, network, and database procedures MCP endpoint and tool reference ↗