Skip to main content
Current Architecture: ReptiDex uses AWS ECS Fargate for serverless container orchestration with ARM64 Graviton2 processors. All infrastructure is managed via CloudFormation templates, and applications are deployed as Docker containers via ECR and GitHub Actions.

​
ReptiDex Deployment Guide

Comprehensive deployment procedures for ReptiDex infrastructure and applications, covering both AWS CloudFormation infrastructure and application deployment strategies.

​
Quick Navigation

Infrastructure
AWS CloudFormation
Applications
Frontend & Backend
CI/CD
Automated deployments
Troubleshooting
Common issues

​
Infrastructure Deployment

​
Prerequisites

Required Setup

AWS Requirements:
  • AWS CLI installed and configured
  • CloudFormation, ECS, ECR, RDS, IAM permissions
  • AWS SSO configured for reptidex-dev profile
Development Tools:
  • Node.js 20+ and pnpm installed
  • Docker with ARM64/AMD64 support
  • Git configured with ReptiDex credentials
  • GitHub Packages authentication token (for private npm packages)

​
CloudFormation Infrastructure

reptidex uses AWS CloudFormation templates for infrastructure as code. Templates are organized in deployment order:
  • Development
  • Production

​
Development Environment Deployment

Cost: ~$150/month | Uptime: 24/7 (on-demand scaling)
cd infrastructure

# 1. Validate all templates
./scripts/validate.sh

# 2. Deploy foundation (VPC and networking)
AWS_PROFILE=reptidex-dev ./scripts/deploy.sh dev vpc

# 3. Deploy security (IAM roles and security groups)
AWS_PROFILE=reptidex-dev ./scripts/deploy.sh dev security

# 4. Deploy database layer
AWS_PROFILE=reptidex-dev ./scripts/deploy.sh dev database

# 5. Deploy compute (ALB and supporting resources)
AWS_PROFILE=reptidex-dev ./scripts/deploy.sh dev compute

# 6. Deploy ECS cluster and services
AWS_PROFILE=reptidex-dev ./scripts/deploy.sh dev ecs

# 7. Verify deployment
aws cloudformation list-stacks \
  --stack-status-filter CREATE_COMPLETE UPDATE_COMPLETE \
  --query 'StackSummaries[?starts_with(StackName, `reptidex-dev`)].{Name:StackName,Status:StackStatus}' \
  --output table
Development Features:
  • Multi-AZ deployment (2 AZs for HA)
  • ECS Fargate with ARM64 Graviton2 (0.25-0.5 vCPU per task)
  • db.t4g.micro RDS and cache.t4g.micro ElastiCache
  • 2x NAT gateways for private subnet egress
  • Container Insights for monitoring
  • 7-day CloudWatch log retention

​
Infrastructure Templates Overview

TemplatePurposeResourcesDependencies
01-vpc.yamlNetwork foundationVPC, subnets, IGW, NAT gateway, flow logsNone
02-security.yamlSecurity infrastructureSecurity groups, IAM roles, policiesVPC
03-database.yamlData layerRDS PostgreSQL, ElastiCache RedisVPC, Security
04-compute.yamlLoad balancer and routingALB, Target Groups, Listener Rules, DNSVPC, Security, Database
05-ecs.yamlContainer orchestrationECS Cluster, Fargate Services, Task DefinitionsVPC, Security, Compute

​
Infrastructure Cleanup

​
⚠️ Infrastructure Cleanup (Destructive Operation)

CloudFormation Stack Deletion: Similar to terraform destroy, reptidex provides a cleanup script for completely removing AWS infrastructure. This operation is irreversible and will permanently delete all resources.
  • Complete Cleanup
  • Selective Cleanup

​
Delete All Infrastructure

cd infrastructure

# Delete all stacks in proper dependency order
./scripts/cleanup.sh dev

# Or for production (requires additional confirmation)
./scripts/cleanup.sh prod
Cleanup Process:
  1. Prompts for explicit DELETE confirmation
  2. Deletes stacks in reverse dependency order:
    • 06-monitoring → 05-storage → 04-compute → 03-database → 02-security → 01-vpc
  3. Waits for each stack deletion to complete
  4. Shows progress and any failures
What Gets Deleted:
  • All ECS services and task definitions
  • ECS Fargate cluster
  • RDS databases and ElastiCache clusters
  • Application Load Balancer and target groups
  • ECR repositories (if empty)
  • Route53 DNS records
  • All IAM roles and security groups created by templates

​
Cleanup Safety Features

Safety Confirmations

Multiple Confirmation Steps:
  • Environment confirmation (dev/prod)
  • Stack list preview before deletion
  • Explicit DELETE typing requirement
  • Progress tracking with failure handling

Failure Handling

Robust Error Handling:
  • Skips non-existent stacks gracefully
  • Shows stack events for failed deletions
  • Continues with remaining stacks on partial failures
  • Provides detailed error messages and troubleshooting info

​
Common Cleanup Issues

  • S3 Bucket Issues
  • Database Issues
  • Manual Cleanup
S3 Buckets Not Empty:
# Empty S3 buckets before stack deletion
aws s3 rm s3://reptidex-dev-assets --recursive
aws s3 rm s3://reptidex-dev-uploads --recursive
aws s3 rm s3://reptidex-dev-backups --recursive
aws s3 rm s3://reptidex-dev-logs --recursive

# Then retry cleanup
./scripts/cleanup.sh dev storage

​
Application Deployment

​
Development Application Deployment

  • Local Development
  • AWS Development

​
Local Development Setup ```bash # 1. Clone and setup workspace git

clone https://github.com/reptidex/reptidex.git cd reptidex # 2. Install dependencies pnpm install # 3. Start backend services (Docker) ./scripts/dev.sh backend # 4. Start frontend applications (local) ./scripts/dev.sh frontend # 5. Verify services curl http://localhost:8001/health # Core API curl http://localhost:8002/health # Animal API curl http://localhost:3000 # Public web app ``` Local Architecture: - Backend: Docker containers with PostgreSQL and Redis - Frontend: Local Vite dev servers with hot reload - Environment: Mixed development for optimal developer experience

​
Production Application Deployment

​
Production Deployment Process

Zero-Downtime ECS Deployment Strategy:
  1. Rolling Updates: ECS Fargate rolling deployment with health checks
  2. Deployment Circuit Breaker: Automatic rollback on task failures
  3. Database Migrations: Run via ECS task before service update
  4. Health Check Monitoring: ALB health checks validate new tasks
# Production deployment (via GitHub Actions)
# Triggered on merge to main branch

# Manual deployment steps:
# 1. Build ARM64 Docker images
docker buildx build --platform linux/arm64 -t repti-core:latest backend/repti-core

# 2. Tag and push to ECR
aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin $ECR_REGISTRY
docker tag repti-core:latest $ECR_REGISTRY/repti-core:$VERSION
docker push $ECR_REGISTRY/repti-core:$VERSION

# 3. Update ECS service (rolling deployment)
aws ecs update-service \
  --cluster prod-reptidex-cluster \
  --service prod-reptidex-core \
  --force-new-deployment

# 4. Monitor deployment
aws ecs wait services-stable \
  --cluster prod-reptidex-cluster \
  --services prod-reptidex-core

​
CI/CD Pipeline

​
GitHub Actions Workflow

  • Infrastructure
  • Applications

​
Infrastructure CI/CD

name: Infrastructure Deploy
on:
  push:
    branches: [main]
    paths: ['infrastructure/**']
  pull_request:
    paths: ['infrastructure/**']

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - name: Validate CloudFormation templates
      - name: Lint YAML syntax
      - name: Cost estimation
      - name: Security scanning
  
  deploy-dev:
    needs: validate
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-latest
    steps:
      - name: Deploy to development
      - name: Run integration tests
      - name: Generate deployment report
  
  deploy-prod:
    needs: validate
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    environment: production
    steps:
      - name: Deploy to production
      - name: Health checks
      - name: Rollback on failure

​
Deployment Environments

Development

Purpose: Feature development and testing Trigger: Pull request creation Approval: Automatic Rollback: Automatic on failure

Staging

Purpose: Pre-production validation Trigger: Merge to main branch Approval: Automatic Rollback: Manual trigger available

Production

Purpose: Live customer-facing environment Trigger: Manual promotion from staging Approval: Required (manual approval) Rollback: Automated with monitoring triggers

​
Monitoring and Health Checks

​
Application Health Endpoints

All reptidex services expose health check endpoints for monitoring: 
# Frontend service health
curl https://dev.reptidex.com/health
# Response: {"status": "healthy"}

# Backend service health (subdomain-based routing)
curl https://api-dev.reptidex.com/api/v1/health
curl https://animal-api-dev.reptidex.com/api/v1/health
curl https://commerce-api-dev.reptidex.com/api/v1/health
curl https://media-api-dev.reptidex.com/api/v1/health
curl https://community-api-dev.reptidex.com/api/v1/health
curl https://ops-api-dev.reptidex.com/api/v1/health

# Response: {"status": "healthy", "version": "1.0.0", "database": "connected"}

​
Deployment Monitoring

  • Infrastructure
  • Applications

​
Infrastructure Monitoring CloudFormation Stack Monitoring: - Stack

creation/update events - Resource creation status - Stack drift detection - Cost monitoring and alerts Network Monitoring: - VPC Flow Logs analysis
  • Security group compliance - NAT Gateway usage and costs - Internet Gateway traffic patterns

​
Troubleshooting

​
Common Infrastructure Issues

  • CloudFormation
  • Networking
  • Applications

​
CloudFormation Deployment Issues

Stack Creation Failures:
# Check stack events for detailed error messages
aws cloudformation describe-stack-events --stack-name reptidex-dev-01-vpc

# Validate template syntax
./scripts/validate.sh 01-vpc

# Check resource limits
aws service-quotas get-service-quota --service-code vpc --quota-code L-F678F1CE
Common Fixes:
  • Verify AWS credentials and permissions
  • Check CIDR block overlaps in parameters
  • Ensure availability zones exist in target region
  • Verify instance types are available in region

​
Emergency Procedures

​
Emergency Rollback Procedures

Infrastructure Rollback: bash # Rollback CloudFormation stack to previous version aws cloudformation cancel-update-stack --stack-name reptidex-prod-compute # Or rollback to specific change set aws cloudformation execute-change-set --change-set-name rollback-changeset Application Rollback: bash # Rollback to previous Auto Scaling Group launch template ./scripts/rollback-deployment.sh prod --version previous # Or emergency traffic redirect ./scripts/emergency-redirect.sh --target maintenance-page

​
Support Contacts

Infrastructure Issues:
  • Primary: DevOps team
  • Escalation: AWS Support (Business Plan)
  • Emergency: On-call engineer rotation
Application Issues:
  • Primary: Development team
  • Database: Database administrator
  • Frontend: Frontend team lead
This deployment guide covers the complete reptidex deployment process from infrastructure provisioning to application deployment. Regular updates to this documentation ensure alignment with infrastructure changes and deployment process improvements. For the latest deployment procedures, always refer to the scripts in the /infrastructure/scripts/ directory and CI/CD pipeline configurations.