Prerequisites

Everything you need before deploying CloudAtlas. Most items take under 5 minutes to verify.

AWS Account Requirements

CloudAtlas works with a single AWS account or a full AWS Organization with hundreds of member accounts. Multi-account mode requires Organizations to be enabled.

AWS Management (root) account access

You need IAM credentials or an instance role in the account that owns the AWS Organization, or in a standalone account for single-account mode.

AWS Organizations enabledoptional

Required for multi-account scanning. Go to AWS Console → Organizations to check. Single-account deployments can skip this.

STS service available in primary region

STS must be enabled in your chosen primary region (us-east-1 by default). Verify under IAM → Account settings.

EC2 Regions service enabled

CloudAtlas calls ec2:DescribeRegions to discover opted-in regions. This is enabled by default.

IAM Permissions

The IAM setup is the most important step. Incomplete permissions are the most common cause of scan failures. Follow the IAM Setup Guide carefully.

CloudAtlasRootRole in management account

Needs ReadOnlyAccess + organizations:ListAccounts + sts:AssumeRole on child account roles. See IAM Setup Guide for the full policy JSON.

CloudAtlasInventoryRole in every child account

Needs ReadOnlyAccess + trust relationship allowing the management account to assume it. Can be created manually, with CloudFormation StackSets, or automatically via the Settings → Setup Roles wizard.

OrganizationAccountAccessRole exists in child accountsoptional

AWS creates this automatically for accounts created within an Organization. Required only if using the automated role setup wizard. For manually-joined accounts you may need to create it.

Infrastructure Requirements

Docker Engine 24+ and Docker Compose v2

Check with: docker --version && docker compose version. Install via https://docs.docker.com/engine/install/

Linux VPS with 1 vCPU / 1 GB RAM minimum

2 vCPU / 2 GB RAM recommended for organisations with 20+ accounts. Tested on Ubuntu 22.04 and Debian 12.

Outbound HTTPS (port 443) to AWS APIs

The backend connects to AWS service endpoints. Most VPS providers allow this by default.

Domain name pointed at the VPSoptional

Required for Traefik HTTPS. Add an A record pointing your domain to the VPS public IP.

Ports 80 and 443 open in the VPS firewalloptional

Traefik uses port 80 for ACME HTTP-01 challenge and port 443 for HTTPS. Not needed for local / HTTP-only deployments.

Network Connectivity

Access to AWS STS endpoint

https://sts.amazonaws.com — used for assume-role calls.

Access to AWS Organizations endpoint

https://organizations.us-east-1.amazonaws.com — used to list accounts.

Access to all AWS regional service endpoints

CloudAtlas calls EC2, RDS, Lambda, etc. endpoints in every enabled region. VPC-deployed instances may need NAT Gateway or VPC Endpoints.

Credential Options

CloudAtlas supports three ways to authenticate. Choose the one that fits your deployment:

EC2 / ECS instance role (recommended)

Deploy CloudAtlas on an EC2 instance or ECS task with an IAM role attached. No credentials in env vars. Leave AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY blank in .env.

Static IAM access keys

Set AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY in .env. Create a dedicated IAM user (not root) with CloudAtlasRootPolicy attached.

Root Role ARN assumption

Configure ROOT_ROLE_ARN in .env or Settings page. CloudAtlas first assumes this role using the base credentials (either instance role or access keys), then uses the resulting session for all operations.

Ready? Continue with:

IAM Setup Guide |Deployment Guide