Skip to main content

Documentation Index

Fetch the complete documentation index at: https://arizeai-433a7140.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

​
Prerequisites

AWS Account & CLI Export your AWS Account and Region for future use Before you run any of the CloudFormation or ECR commands, export two env‑vars so you don’t have to repeat your account/region everywhere: 
# grab your AWS account ID and default region from your CLI creds
export ACCOUNT=$(aws sts get-caller-identity --query Account --output text)
export REGION=$(aws configure get region)

​
IAM Permissions

Copy the following JSON file of permissions: permissions.json Before you can deploy any of the CloudFormation stacks above, you’ll want a single, least‑privilege managed policy that your CI/CD user or role can assume.

​
Create the IAM policy

aws iam create-policy \
  --policy-name PhoenixDeployPermissions \
  --policy-document file://deploy-permissions.json
This will return the new policy’s ARN, e.g.: 
arn:aws:iam::123456789012:policy/PhoenixDeployPermissions

​
Attach it to your deploy principal

a) If you use an IAM User: 
aws iam attach-user-policy \
  --user-name <YOUR_DEPLOY_USER> \
  --policy-arn <PASTE ARN HERE>
b) If you use an IAM Role (e.g. CodeBuild or CI/CD): 
aws iam attach-role-policy \
  --role-name <YOUR_DEPLOY_ROLE> \
  --policy-arn <PASTE ARN HERE>
Once attached, that user or role will have exactly the rights needed to stand up all of the VPCs, ECS/Fargate clusters, ECR repos, Secrets Manager secrets, ALBs, CloudWatch Logs, IAM roles, and CloudFormation stacks in this guide

​
Set up ECR (Elastic Container Registry) Repositories for Phoenix and your application

Before deploying Phoenix and your application into ECS/Fargate, you need to host your container images in Amazon Elastic Container Registry (ECR). Here’s a quick rundown:

​
1. Create ECR repositories

Run these once: 
# Repository for the Phoenix UI image
aws ecr create-repository \
  --repository-name phoenix \
  --image-scanning-configuration scanOnPush=true \
  --region $REGION

# Repository for your application (agent, backend, frontend, etc.)
aws ecr create-repository \
  --repository-name my-app \
  --image-scanning-configuration scanOnPush=true \
  --region $REGION
Each command returns the repo URI: 
$ACCOUNT.dkr.ecr.$REGION.amazonaws.com/phoenix
$ACCOUNT.dkr.ecr.$REGION.amazonaws.com/my-app

​
2. Authenticate Docker to ECR

aws ecr get-login-password --region $REGION \
  | docker login \
    --username AWS \
    --password-stdin $ACCOUNT.dkr.ecr.$REGION.amazonaws.com
This writes your Docker credentials so you can push and pull.

​
3. Push Phoenix and your apps (backend, frontend, db)

If you’ve built locally: 
# Tag your local Phoenix image
docker pull arizephoenix/phoenix
docker tag arizephoenix/phoenix:latest \
  $ACCOUNT.dkr.ecr.$REGION.amazonaws.com/phoenix:latest

# Push to ECR
docker push $ACCOUNT.dkr.ecr.$REGION.amazonaws.com/phoenix:latest

# Repeat for your app
docker tag my-app:latest \
  $ACCOUNT.dkr.ecr.$REGION.amazonaws.com/my-app:latest
docker push $ACCOUNT.dkr.ecr.$REGION.amazonaws.com/my-app:latest

​
Create VPCs and Subnets

Copy this CloudFormation template: phoenix-network.yml This template:
  1. Creates a VPC (10.0.0.0/16 for example) with DNS support
  2. Provisions two public subnets (one per AZ) for your Internet‑facing components (ALBs, NAT gateway)
  3. Provisions two private subnets (one per AZ) for your ECS tasks (Phoenix, agents, backend services)
  4. Deploys a NAT Gateway in the first public subnet so private tasks can reach out (for secrets, Docker registries, external APIs)
  5. Exports the VPC ID and the comma‑separated Public/Private Subnet IDs for easy consumption by downstream stacks

​
Deploy with:

aws cloudformation deploy \
  --template-file phoenix-network.yml \
  --stack-name phoenix-network \
  --parameter-overrides \
      AZ1=us-west-2a \
      AZ2=us-west-2b \
  --capabilities CAPABILITY_NAMED_IAM
Make sure to change AZ1 and AZ2 to match your region. You can now access your VPC and public + private subnet IDs at AWS -> CloudFormation -> Stacks -> phoenix-network -> Outputs.

​
Extending for multiple components

If you plan to run multiple services (e.g. a separate frontend, backend, worker pool), consider:
  • Additional subnets You might carve out extra AZ‑distributed subnets (e.g. “app‑subnets”, “db‑subnets”) with their own route tables and security rules.
  • Security groups per tier
    • ALB SG: allows inbound HTTP(S) from 0.0.0.0/0
    • App SG: allows inbound from the ALB SG on your HTTP port
    • DB SG: allows inbound only from your App SG on your database port

​
Deploy Phoenix (with Authentication)

Copy this CloudFormation template: phoenix-auth.yml You are now ready to deploy Phoenix to AWS. Deploy the phoenix-auth.yml stack Consume the network stack’s outputs (VPC‑ID, PublicSubnetIds, PrivateSubnetIds) along with your new ECR URI: 
aws cloudformation deploy \
  --template-file phoenix-auth.yml \
  --stack-name phoenix-auth \
  --capabilities CAPABILITY_NAMED_IAM \
  --parameter-overrides \
    PhoenixImageUri=$ACCOUNT.dkr.ecr.$REGION.amazonaws.com/phoenix:latest \
    VpcId=$(aws cloudformation describe-stacks \
            --stack-name phoenix-network \
            --query 'Stacks[0].Outputs[?OutputKey==`VpcId`].OutputValue' \
            --output text) \
    PublicSubnetIds=$(aws cloudformation describe-stacks \
            --stack-name phoenix-network \
            --query 'Stacks[0].Outputs[?OutputKey==`PublicSubnetIds`].OutputValue' \
            --output text) \
    PrivateSubnetIds=$(aws cloudformation describe-stacks \
            --stack-name phoenix-network \
            --query 'Stacks[0].Outputs[?OutputKey==`PrivateSubnetIds`].OutputValue' \
            --output text)
Fetch your Phoenix URL 
PHOENIX_URL=$(aws cloudformation describe-stacks \
  --stack-name phoenix-auth \
  --query 'Stacks[0].Outputs[?OutputKey==`PhoenixURL`].OutputValue' \
  --output text)
Log in and create your System API key
  • In your browser, go to $PHOENIX_URL.
  • Sign in as admin@localhost / admin.
  • Set a new admin password.
  • Go to Settings → API Keys and Create System Key.
  • Copy the new key (you’ll need it in the next step).
IMPORTANT: Security‑group ingress is wide open (0.0.0.0/0 on port 80). You should tighten it if you know your CIDR or are behind a corporate proxy.

​
Store Phoenix API Key + other API Keys

Once you have your Phoenix System API key, bundle it (and any other service keys) into AWS Secrets Manager: 
# Store Phoenix API key
aws secretsmanager create-secret \
  --name phoenix-system-api-key \
  --description "Phoenix System API Key for OTLP traces" \
  --secret-string '{"PHOENIX_API_KEY":"<PASTE SYSTEM KEY HERE>"}'

# (Optional) Store other service keys similarly:
aws secretsmanager create-secret \
  --name openai-api-key \
  --description "OpenAI API key for LLM calls" \
  --secret-string '{"OPENAI_API_KEY":"<PASTE OPENAI KEY HERE>"}'
You can now reference these secrets in your downstream CloudFormation templates (e.g. in your application stacks) via the PhoenixArn, OpenAIArn, etc., parameters.

​
Deploying your App that ships Spans to Phoenix

Copy this CloudFormation template: app.yml This CloudFormation stack (app.yml) launches:
  • An ECS Cluster
  • An IAM Task Execution Role & Task Role (to pull images, read secrets)
  • A Security Group that allows outbound Internet access
  • A Log Group for container logs
  • An ECS Task Definition (family: app)
  • An ECS Service (Fargate) running one copy of the “app” container
The app container will:
  1. Read your OTLP endpoint and Phoenix API key from Secrets Manager
  2. Read your other API keys from Secrets Manager
  3. Emit spans to your Phoenix deployment
IMPORTANT: This template assumes only one secret is being used (OpenAI API Key). Make sure to add ARNs for additional secrets in the list of parameters (line 34 and line 86) and store those additional secrets as environment variables (line 134). Template parameters
ParameterDescriptionExample
AgentImageUriECR URI (with tag) of your agent container123456789012.dkr.ecr.us-west-2.amazonaws.com/agent:latest
PhoenixHostDNS name (no scheme) of your Phoenix UI load‑balancerphoenix-auth-ALB-abc123.us-west-2.elb.amazonaws.com
VpcIdYour VPC IDvpc-0abc123def456ghi7
PublicSubnetIdsComma‑separated public subnets for the NAT/ALBsubnet-aaa111,subnet-bbb222
PrivateSubnetIdsComma‑separated private subnets for your ECS taskssubnet-ccc333,subnet-ddd444
OpenAIArnARN of Secrets Manager secret holding {"OPENAI_API_KEY": "…"}arn:aws:secretsmanager:us-west-2:920904165384:secret:openai-key
PhoenixArnARN of secret holding {"PHOENIX_API_KEY": "…"}arn:aws:secretsmanager:us-west-2:920904165384:secret:phoenix-key
Example deploy command (add additional ARNs for more secrets): 
aws cloudformation deploy \
  --template-file app.yml \
  --stack-name app \
  --parameter-overrides \
      AgentImageUri=123456789012.dkr.ecr.us-west-2.amazonaws.com/agent:latest \
      PhoenixHost=phoenix-auth-ALB-abc123.us-west-2.elb.amazonaws.com \
      VpcId=vpc-0abc123def456ghi7 \
      PublicSubnetIds=subnet-aaa111,subnet-bbb222 \
      PrivateSubnetIds=subnet-ccc333,subnet-ddd444 \
      OpenAIArn=arn:aws:secretsmanager:us-west-2:920904165384:secret:openai-key \
      PhoenixArn=arn:aws:secretsmanager:us-west-2:920904165384:secret:phoenix-key \
  --capabilities CAPABILITY_NAMED_IAM
Once complete, ECS will spin up your agent task, and you can verify in the console: 
# See the running task
aws ecs list-tasks --cluster agent-only --output table

# Check logs for any “Connectivity to http://<PhoenixHost>” output
aws logs tail \
  --log-group-name /aws/ecs/agent \
  --since 5m
Now your traces should flow from the agent into your Phoenix project!

​
(Optional) Extending for Additional Components (Frontend, DB, etc.)

Once you have Phoenix + your agent/LLM task up and running, you can easily add more services to the same VPC:
  1. Create new ECR repos for your frontend, backend, DB‑migrations job, worker service, etc.
  2. Add new TaskDefinitions / Services to your app.yml (or split each into its own CFN stack): 
    Parameters:
  FrontendImageUri: …
  BackendImageUri: …
  DbMigrationImageUri: …

Resources:
  # reuse same VpcId, SubnetIds, SecurityGroup
  FrontendTaskDef:
    Type: AWS::ECS::TaskDefinition
    Properties:
      Family: frontend
      ContainerDefinitions:
        - Name: frontend
          Image: !Ref FrontendImageUri
          PortMappings: [{ContainerPort: 80}]
          # …env & secrets…
  FrontendService:
    Type: AWS::ECS::Service
    Properties:
      Cluster: !Ref Cluster
      DesiredCount: 2
      TaskDefinition: !Ref FrontendTaskDef
      LoadBalancers:  # attach to same (or new) ALB
  3. Subnet segmentation If you want stricter isolation, you can carve out “app‑subnets” vs “db‑subnets”, each with its own route table and SG rules. Just update phoenix-network.yml to output those extra subnet IDs.
  4. Security groups per tier
    • ALB SG → allows 0.0.0.0/0 on 80/443
    • App SG → allows inbound from ALB SG on 80
    • DB SG → allows inbound from App SG on 5432 (Postgres) or 3306 (MySQL)
With these patterns you can grow from one simple “agent-only” service into a multi‑tier architecture, all launched and managed via CloudFormation.