Skip to content

docs: add comprehensive AWS ECS self-hosting guide#5302

Merged
vmatsiiako merged 4 commits intomainfrom
devin/1769624443-improve-aws-native-guide
Feb 4, 2026
Merged

docs: add comprehensive AWS ECS self-hosting guide#5302
vmatsiiako merged 4 commits intomainfrom
devin/1769624443-improve-aws-native-guide

Conversation

@devin-ai-integration
Copy link
Contributor

@devin-ai-integration devin-ai-integration bot commented Jan 28, 2026 •
edited
Loading

Context

This PR adds a new comprehensive self-hosting guide for deploying Infisical on AWS using ECS Fargate, RDS PostgreSQL, ElastiCache Redis, and Application Load Balancer. This addresses the missing AWS deployment documentation that was identified as a gap in the self-hosting guides.

The guide includes all the sections requested:

  • System requirements
  • Step-by-step deployment with verification commands after each major step
  • IAM policy JSON examples (not just descriptions)
  • SMTP/email configuration with AWS SES
  • Custom domain setup with Route 53 and ACM
  • Container debugging instructions (ECS Exec)
  • Database migration handling
  • VPC endpoint setup for air-gapped environments
  • Backup strategy and upgrade instructions
  • Infrastructure as Code templates (Terraform and CloudFormation)
  • Comprehensive troubleshooting section (7 common issues)

The health check endpoint has been verified as /api/status (not /api/health as mentioned in the original PR #5106).

Updates since last revision

  • Removed cost considerations section per user request
  • Fixed whitespace/indentation in docs.json (only the new aws-native entry is added now)
  • Added note advising users to scope down KMS permissions to specific key ARNs for production
  • Added note about additional ALB security options (CloudFront, WAF, IP allowlists)
  • Removed broken Terraform module link (infisical-terraform-aws repo doesn't exist) and clarified the example is a starting point

Steps to verify the change

  1. Preview the documentation in Mintlify to verify formatting renders correctly
  2. Spot-check AWS CLI commands for syntax correctness
  3. Review IAM policy examples for security best practices

Human review checklist

  • Verify IAM policies follow least-privilege principles (note: examples use wildcards with guidance to scope down for production)
  • Confirm CloudFormation/Terraform examples are useful (note: they are simplified/partial starting points)
  • Check that security group configurations are secure
  • Confirm health check endpoint /api/status is correct for Infisical

Type

  • Fix
  • Feature
  • Improvement
  • Breaking
  • Docs
  • Chore

Checklist

  • Title follows the conventional commit format: type(scope): short description (scope is optional, e.g., fix: prevent crash on sync or fix(api): handle null response).
  • Tested locally
  • Updated docs (if needed)
  • Read the contributing guide

Link to Devin run: https://app.devin.ai/sessions/de8b36ae4d4c4287ace71741aef029fe
Requested by: ashwin@infisical.com

@devin-ai-integration @ashwin-infisical
docs: add comprehensive AWS ECS self-hosting guide
919c7bf 
Co-Authored-By: ashwin@infisical.com <ashwin@infisical.com>
@devin-ai-integration
Copy link
Contributor Author

devin-ai-integration bot commented Jan 28, 2026

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

  • Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
  • Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

  • Disable automatic comment and CI monitoring

@maidul98
Copy link
Collaborator

maidul98 commented Jan 28, 2026 •
edited
Loading

✅ Snyk checks have passed. No issues have been found so far.

Status Scanner Critical High Medium Low Total (0)
✅ Open Source Security 0 0 0 0 0 issues

💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.

@greptile-apps
Copy link
Contributor

greptile-apps bot commented Jan 28, 2026 •
edited
Loading

Greptile Overview

Greptile Summary

This PR adds a comprehensive AWS ECS self-hosting guide that fills a gap in the documentation. The guide covers deploying Infisical on AWS using ECS Fargate, RDS PostgreSQL, ElastiCache Redis, and ALB.

Key additions:

  • Step-by-step deployment instructions with verification commands
  • Complete IAM policy examples for task execution and task roles
  • Security configurations (security groups, encryption, VPC setup)
  • SMTP/email setup with AWS SES
  • Custom domain configuration with Route 53 and ACM
  • Container debugging with ECS Exec
  • Database migration handling
  • VPC endpoints for air-gapped environments
  • Backup strategies and upgrade procedures
  • Infrastructure as Code templates (Terraform and CloudFormation)
  • Comprehensive troubleshooting section covering 7 common scenarios

Previous review feedback addressed:

  • KMS permissions now include a Note advising to scope down to specific key ARNs for production
  • ALB security includes a Note about additional security options (CloudFront, WAF, IP allowlists)
  • Broken Terraform module link removed with clarification that examples are starting points
  • Whitespace issues in docs.json have been fixed

The documentation follows best practices and provides clear guidance for production deployments. Health check endpoint /api/status has been verified in the codebase.

Confidence Score: 4/5

  • This documentation PR is safe to merge with minimal risk
  • Score reflects comprehensive documentation that addresses previous feedback and provides production-ready guidance. Minor deduction for complexity and breadth of AWS commands that should be spot-checked by someone familiar with the AWS services involved
  • No files require special attention - previous review concerns have been addressed

Important Files Changed

Filename Overview
docs/docs.json Added aws-native entry to deployment options navigation menu
docs/self-hosting/deployment-options/aws-native.mdx New comprehensive AWS ECS self-hosting guide with step-by-step instructions, IAM policies, IaC templates, and troubleshooting. Previous security concerns addressed.

greptile-apps[bot]
greptile-apps bot reviewed Jan 28, 2026
View reviewed changes
Copy link
Contributor

@greptile-apps greptile-apps bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

2 files reviewed, 5 comments

Edit Code Review Agent Settings | Greptile

@devin-ai-integration @ashwin-infisical
fix: address Greptile feedback on AWS guide
099c049 
- Fix whitespace/indentation in docs.json
- Add note about scoping down KMS permissions for production
- Add note about additional ALB security options (CloudFront, WAF, IP allowlists)
- Remove broken Terraform module link and clarify example is a starting point

Co-Authored-By: ashwin@infisical.com <ashwin@infisical.com>
@devin-ai-integration @ashwin-infisical
docs: remove cost considerations section from AWS guide
7a667f3 
Co-Authored-By: ashwin@infisical.com <ashwin@infisical.com>
@devin-ai-integration devin-ai-integration bot mentioned this pull request Jan 28, 2026
Merged
10 tasks
@ashwin-infisical
Copy link
Collaborator

ashwin-infisical commented Jan 28, 2026

@greptileai Can you re-review this PR with all of your comments addressed?

@devin-ai-integration @ashwin-infisical
docs: remove docs.json changes from AWS guide PR
2cb0c3d 
The docs.json navigation updates will be handled in a separate PR (#5305).

Co-Authored-By: ashwin@infisical.com <ashwin@infisical.com>
@vmatsiiako vmatsiiako merged commit 09e1b8a into main Feb 4, 2026
7 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@vmatsiiako vmatsiiako vmatsiiako approved these changes

+1 more reviewer

@greptile-apps greptile-apps[bot] greptile-apps[bot] left review comments

Reviewers whose approvals may not affect merge requirements

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@maidul98 @ashwin-infisical @vmatsiiako