Launch

You launch Tracemill once, as a CloudFormation stack. Everything after that, including single sign-on and new releases, is a stack update.

PrerequisitesCopy Anchor Link

• An AWS account and Region. The stack runs in us-east-1 or us-west-2.
• The template URL. Use the one on the AWS Marketplace fulfilment page, or the one Tracemill gave you.
• Permission to create the stack. The person launching needs rights to create CloudFormation stacks with the CAPABILITY_IAM and CAPABILITY_NAMED_IAM capabilities (the stack creates named IAM roles), and to create the resources it holds: VPC and EC2 networking, RDS, ECS, Elastic Load Balancing, Cognito, Lambda, Step Functions, EventBridge, SNS, Secrets Manager, KMS, S3, AWS WAF, CloudWatch Logs and IAM. Updates later need the same rights.
• A stack name of 44 characters or fewer. Resource names are derived from it, and the longest must fit Lambda's 64-character function-name limit.
• A console hostname and its certificate. Pick a hostname in a domain you control, such as tracemill.example.com, and issue an ACM certificate for it in the Region you launch in. The certificate must be issued, not pending validation.
• Someone who can create a DNS record for that hostname after the launch. See DNS.

NetworkCopy Anchor Link

By default the stack creates its own VPC. Leave VpcId empty and set AvailabilityZones to two Availability Zones that offer your database instance class with gp3 storage. AZ names differ per account, so list them first:

aws rds describe-orderable-db-instance-options --region <Region> \
  --engine postgres --engine-version 17.9 --db-instance-class db.t3.medium \
  --query 'OrderableDBInstanceOptions[?StorageType==`gp3`]|[0].AvailabilityZones[].Name'

The created VPC is split into four /20 subnets, so VpcCidr must be /16 to /18. The default is 10.30.0.0/16.

To use an existing VPC instead, set VpcId, set VpcCidr to that VPC's CIDR, and give two private subnets in different Availability Zones in PrivateSubnetIds. The private subnets need outbound internet access, through a NAT gateway or equivalent: the tasks pull the server image, fetch releases and content, and call AWS APIs, and the stack adds no interface endpoints. An internet-facing load balancer also needs two public subnets in PublicSubnetIds.

DatabaseCopy Anchor Link

By default the stack creates an RDS for PostgreSQL 17 instance (db.t3.medium, Multi-AZ, 50 GiB gp3). To use an existing instance instead, it must:

• run PostgreSQL 17 and contain a database named tracemill (the stack connects to that name and doesn't create it);
• have its master credentials in a Secrets Manager secret shaped {"username": "...", "password": "..."}. If that secret is encrypted with a customer-managed KMS key, pass the key's ARN in ExistingDbSecretKmsKeyArn;
• accept connections on port 5432 from the stack's server security group (output ServerSecurityGroupId). The first transition connects to the database before the launch finishes, so add that rule as soon as the group appears in the stack's Resources tab, or allow your private subnets' CIDR ranges before you launch.

Set ExistingDbInstanceIdentifier, ExistingDbEndpointAddress and ExistingDbMasterSecretArn together.

Internet access the deployment needsCopy Anchor Link

Launching downloads the template from Tracemill's release bucket in us-east-1 (tracemill-releases-prod-us-east-1 on Amazon S3, whatever Region you launch in) and the Lambda package from the bucket in your Region (tracemill-releases-prod-<Region>), and pulls the server image from Amazon ECR. Once running, the deployment keeps connecting to Tracemill's release and content feed (ContentFeedBaseUrl, https://dl.tracemill.io by default). Error reports go to Tracemill's Sentry only when SentryReporting is enabled. Security review has the full list.

Launch the stackCopy Anchor Link

1. Open the CloudFormation console in your Region, choose Create stack → With new resources, and paste the template URL. From AWS Marketplace, the fulfilment page opens this for you.
2. Name the stack (44 characters or fewer).
3. Fill in the parameters. Parameters explains each one. The ones you must decide:
   • TenantName and TenantSlug: your organisation's display name and URL slug.
   • DeploymentReport: a required choice with no default. Today enabled only records your consent: this release sends no report. See Security review.
   • ConsoleHostname and CertificateArn.
   • AvailabilityZones (created VPC) or the existing-VPC parameters.
   • Single sign-on: leave SsoType at none unless your identity provider app is already set up. You can configure it from the console afterwards.
   • AdminEmail: with single sign-on configured at launch, the first person to sign in through it with this address becomes the owner. Without single sign-on, leave it empty: the first owner signs in through emergency access.
   • EmergencyAccessMode: who may use emergency access. Decide before the launch; see Emergency access.
   • AlertEmail: where stack notices go. Set it; a failed release is reported here, and it may be your only notice while the console is down.
4. On Configure stack options, leave the stack failure option at Roll back all resources.
5. Acknowledge that the stack creates IAM resources with custom names, and submit.

The same launch from the AWS CLI. Put the parameters in a JSON file, because the CLI's shorthand syntax splits values on commas:

[
  { "ParameterKey": "TenantName", "ParameterValue": "Example Corp" },
  { "ParameterKey": "TenantSlug", "ParameterValue": "example" },
  { "ParameterKey": "DeploymentReport", "ParameterValue": "disabled" },
  { "ParameterKey": "ConsoleHostname", "ParameterValue": "tracemill.example.com" },
  { "ParameterKey": "CertificateArn", "ParameterValue": "<certificate ARN>" },
  { "ParameterKey": "AvailabilityZones", "ParameterValue": "<az-1>,<az-2>" },
  { "ParameterKey": "AlertEmail", "ParameterValue": "<you@example.com>" }
]

aws cloudformation create-stack --region <Region> --stack-name <stack> \
  --template-url <template URL> \
  --capabilities CAPABILITY_IAM CAPABILITY_NAMED_IAM \
  --parameters file://params.json
aws cloudformation wait stack-create-complete --region <Region> --stack-name <stack>

If you set AlertEmail, confirm the SNS subscription from the email AWS sends.

How long it takesCopy Anchor Link

Expect about 20 to 25 minutes, most of it RDS creating a Multi-AZ instance. After the database, the stack runs its first transition (it sets up the database schema; about a minute), then starts the server.

After the launchCopy Anchor Link

1. Create the DNS record from the AlbDnsName output. See DNS.
2. Open the ConsoleUrl output.
3. Sign in:
   • Single sign-on configured at launch, with AdminEmail: sign in through your identity provider with that address.
   • No single sign-on yet: the sign-in page offers Use emergency access. Sign in that way, then set up single sign-on under Settings → Single sign-on and invite the first members. See Single sign-on.

To check health without signing in, request https://<ConsoleHostname>/readyz; it returns 200 once the server is ready.

If the launch fails, the first failed event on the stack's Events tab names the cause. Several resources outlive a deleted stack by design; Teardown lists them and how to remove them.