hecks 3.0.4 → 3.1.0

data/lib/hecks/ports/persistence/plugins/era/era_check.rb

@@ -16,7 +16,7 @@ module Hecks
 
       # Runs both halves of the era gate over every bluebook in a registry.
       #
-      # Looks up each bluebook's own source separately: `uses_framework` can share a boot between
+      # Looks up each bluebook's own source separately: `attaches` can share a boot between
       # the domain's own bluebook and a differently-sourced one, so one file read once and reused
       # for every bluebook would attribute the wrong text.
       #
@@ -84,7 +84,7 @@ module Hecks
       # Reads the source text one bluebook was declared in, wherever that source lives.
       #
       # Matched by declared name, not position: a domain directory using
-      # `uses_framework` may hold more than one file, and a framework
+      # `attaches` may hold more than one file, and a framework
       # member or vendored bluebook is excluded from the single-file
       # fallback so its own real source is read, not a sibling's.
       #
@@ -150,11 +150,11 @@ module Hecks
       #
       # @param registry [Runtime::Registry] the registry whose hecksagons are searched
       # @param bluebook_name [String] the bluebook's declared Pascal-case name
-      # @return [String, nil] the package name as written in `uses_embryonaut_bluebook`; nil
+      # @return [String, nil] the package name as written in `attaches ... from: :vendor`; nil
       #   when no hecksagon vendored a package whose name Pascal-cases to `bluebook_name`
       def vendored_bluebook_name_for(registry, bluebook_name)
         registry.hecksagons.each_value do |hecksagon|
-          match = hecksagon.vendored_bluebooks.find { |name| Naming.pascal(name) == bluebook_name }
+          match = hecksagon.vendored_packages.find { |name| Naming.pascal(name) == bluebook_name }
           return match if match
         end
         nil

data/lib/hecks/ports/persistence/plugins/era/postgres_era.rb

@@ -123,7 +123,8 @@ module Hecks
         raise unless defined?(PG::Error) && e.is_a?(PG::Error)
 
         raise Runtime::WiringError,
-              "cannot bind PostgresEra at #{declared} for #{name}: #{e.message.strip}"
+              "cannot bind PostgresEra at #{declared} for #{name}: #{e.message.strip} " \
+              "-- to run without a database, set HECKS_ENVIRONMENT=memory (a domain needs an environments/memory overlay)"
       end
 
       # Joins the process's shared connection for the declared database and schema, so every

data/lib/hecks/projections/deploy/box/settings.rb

@@ -0,0 +1,248 @@
+module Hecks
+  module Projections
+    module Deploy
+      module Box
+        # Resolves a world's `deployed_to("AwsBox")` settings into the checked plan the box
+        # generator renders from.
+        #
+        # Every string that reaches a template or a script is matched against a conservative
+        # pattern first, so a world file cannot splice shell, YAML or Caddy syntax into the output.
+        # A setting the world leaves out resolves to the default the golden stack was built with.
+        module Settings
+          NAME        = /\A[a-z][a-z0-9-]{0,40}\z/
+          REPOSITORY  = %r{\A[a-z0-9][a-z0-9._/-]{1,100}\z}
+          URL_PATH    = %r{\A/[A-Za-z0-9._~!$&'()*+,;=:@%/-]*\z}
+          SECRET_NAME = %r{\A[A-Za-z0-9/_+=.@-]{1,256}\*?\z}
+          ENV_KEY     = /\A[A-Za-z_][A-Za-z0-9_]*\z/
+          ENV_VALUE   = /\A[^\x00-\x1f\x7f]*\z/
+          HEADER      = /\A[A-Za-z][A-Za-z0-9-]{0,63}\z/
+          DB_NAME     = /\A[a-zA-Z][a-zA-Z0-9]{0,62}\z/
+          ENGINE      = /\A\d{2}(\.\d{1,2})?\z/
+          PREFIX      = /\A[a-z][a-z0-9-]{0,20}\z/
+          IMAGE       = %r{\A[a-z0-9][a-z0-9._/:@-]{1,200}\z}
+          # Default images, each a version tag plus the digest of its multi-architecture index,
+          # so a rebuilt box pulls the same bytes.
+          TUNNEL_IMAGE = "cloudflare/cloudflared:2026.9.3" \
+                         "@sha256:072c067d25ccbe61d46e18f0d0723255f2bb5304f7317caa95b27031520ff92c".freeze
+          PROXY_IMAGE  = "public.ecr.aws/docker/library/caddy:2.8" \
+                         "@sha256:226d1f059b75399fe19182893c7184591c07b97afc8dfcf44eeb80c9a77a530f".freeze
+          TUNNEL_SHAPE = "tunnel: a hash needs `to` (the container it forwards to) and `token_secret` " \
+                         "(the secret holding the tunnel token)".freeze
+          ORIGIN_PAIR = "origin_header and origin_secret go together: the header a CDN sends, " \
+                        "and the secret that holds its value".freeze
+
+          # One container the box runs: its image repository, its port and its settings.
+          #
+          # @!attribute [r] name [String] the compose service name
+          # @!attribute [r] repository [String] the ECR repository holding its images
+          # @!attribute [r] port [Integer] the port it listens on, on the box's own network
+          # @!attribute [r] env [Hash{String => String}] plain environment variables
+          # @!attribute [r] secrets [Hash{String => String}] environment variable => secret name,
+          #   resolved on the box at deploy time and never written into a template
+          Container = Struct.new(:name, :repository, :port, :env, :secrets, keyword_init: true)
+
+          # A set of URL paths one container serves.
+          #
+          # @!attribute [r] container [String] the container's name
+          # @!attribute [r] paths [Array<String>] Caddy path patterns, such as "/cms/*"
+          Route = Struct.new(:container, :paths, keyword_init: true)
+
+          # A Cloudflare tunnel the box runs as a service, pointed at one container.
+          #
+          # @!attribute [r] container [String] the container the tunnel forwards to
+          # @!attribute [r] port [Integer] that container's port
+          # @!attribute [r] token_secret [String] the secret holding the tunnel token
+          # @!attribute [r] image [String] the cloudflared image
+          Tunnel = Struct.new(:container, :port, :token_secret, :image, keyword_init: true)
+
+          # Everything the generator reads, checked.
+          Plan = Struct.new(
+            :infra_name, :stack_prefix, :instance_type, :volume_gb, :swap_gb, :database_class,
+            :storage_gb, :backup_days, :snapshots_keep, :database_name, :engine_version,
+            :containers, :routes, :default_container, :origin_header, :origin_secret,
+            :secret_prefixes, :tunnel, :tunnel_service, :proxy_image, keyword_init: true
+          ) do
+            # @return [String] the CloudFormation stack that holds the database
+            def rds_stack = "#{stack_prefix}-#{infra_name}-rds"
+
+            # @return [String] the CloudFormation stack that holds the box
+            def box_stack = "#{stack_prefix}-#{infra_name}-box"
+
+            # @return [Container] the container that answers every path no route claims
+            def default
+              containers.find { |c| c.name == default_container }
+            end
+          end
+
+          module_function
+
+          # @param deploy_settings [Hash{Symbol => Object}] the world's `AwsBox` settings
+          # @param target [Object] the validated `BoxTarget` (its instance type, volume, database
+          #   class and storage, already checked by `Declare`)
+          # @param infra_name [String] the stack name the world or the domain gives
+          # @return [Plan] the resolved plan
+          # @raise [ArgumentError] when a setting is missing, malformed or inconsistent
+          def resolve(deploy_settings:, target:, infra_name:)
+            s = deploy_settings
+            check(:stack_name, infra_name, NAME)
+            containers = read_containers(s.fetch(:containers) { raise ArgumentError, missing_containers }, infra_name)
+            header, secret = read_origin(s)
+            tunnel, tunnel_service = read_tunnel(s.fetch(:tunnel, false), containers)
+
+            Plan.new(
+              infra_name: infra_name, stack_prefix: check(:stack_prefix, s.fetch(:stack_prefix, "hecks"), PREFIX),
+              **declared_sizes(target), **read_sizes(s), database_name: read_database_name(s, infra_name),
+              engine_version: check(:engine_version, s.fetch(:engine_version, "16").to_s, ENGINE),
+              containers: containers, routes: read_routes(s.fetch(:routes, []), containers),
+              default_container: read_default(s[:default_container], containers), origin_header: header,
+              origin_secret: secret, secret_prefixes: read_prefixes(s, infra_name),
+              tunnel: tunnel, tunnel_service: tunnel_service,
+              proxy_image: check(:proxy_image, s.fetch(:proxy_image, PROXY_IMAGE), IMAGE)
+            )
+          end
+
+          # @param target [Object] the declared `BoxTarget`
+          # @return [Hash{Symbol => Object}] the sizes `Declare` has already validated
+          def declared_sizes(target)
+            %i[instance_type volume_gb database_class storage_gb].to_h { |key| [key, target.state[key].value] }
+          end
+
+          # @param settings [Hash{Symbol => Object}] the world's settings
+          # @return [Hash{Symbol => Integer}] swap, backup retention and snapshot retention, bounded
+          def read_sizes(settings)
+            {
+              swap_gb:        integer(:swap_gb, settings.fetch(:swap_gb, 2), 0, 64),
+              backup_days:    integer(:backup_days, settings.fetch(:backup_days, 7), 1, 35),
+              snapshots_keep: integer(:snapshots_keep, settings.fetch(:snapshots_keep, 7), 1, 1000)
+            }
+          end
+
+          def read_database_name(settings, infra_name)
+            check(:database_name, settings.fetch(:database_name, infra_name.gsub(/[^a-zA-Z0-9]/, "")), DB_NAME)
+          end
+
+          def read_containers(list, infra_name)
+            raise ArgumentError, missing_containers unless list.is_a?(Array) && !list.empty?
+
+            containers = list.map { |c| read_container(c, infra_name) }
+            names = containers.map(&:name)
+            dup = names.find { |n| names.count(n) > 1 }
+            raise ArgumentError, "containers: two containers are named #{dup.inspect}" if dup
+
+            ports = containers.map(&:port)
+            clash = ports.find { |p| ports.count(p) > 1 }
+            raise ArgumentError, "containers: two containers listen on port #{clash}; they share the box's network" if clash
+
+            containers
+          end
+
+          def read_container(spec, infra_name)
+            raise ArgumentError, "containers: each container is a hash, got #{spec.inspect}" unless spec.is_a?(Hash)
+
+            name = check(:container_name, spec.fetch(:name) { raise ArgumentError, "containers: a container has no name" }, NAME)
+            Container.new(
+              name: name, repository: check(:repository, spec.fetch(:repository, "#{infra_name}-#{name}"), REPOSITORY),
+              port: integer(:port, spec.fetch(:port) { raise ArgumentError, "containers: #{name} has no port" }, 1, 65_535),
+              env: string_map(:env, spec.fetch(:env, {}), ENV_KEY, ENV_VALUE),
+              secrets: string_map(:secrets, spec.fetch(:secrets, {}), ENV_KEY, SECRET_NAME)
+            )
+          end
+
+          def read_routes(list, containers)
+            raise ArgumentError, "routes: expected a list" unless list.is_a?(Array)
+
+            list.map { |spec| read_route(spec, containers) }
+          end
+
+          def read_route(spec, containers)
+            container = spec.fetch(:container) { raise ArgumentError, "routes: a route has no container" }
+            name = check(:route_container, container, NAME)
+            known_container!(:routes, name, containers)
+            paths = Array(spec.fetch(:paths) { raise ArgumentError, "routes: the route for #{name} has no paths" })
+            raise ArgumentError, "routes: the route for #{name} has no paths" if paths.empty?
+
+            Route.new(container: name, paths: paths.map { |p| check(:path, p, URL_PATH) })
+          end
+
+          def read_default(name, containers)
+            return containers.first.name if name.nil? && containers.size == 1
+            raise ArgumentError, "default_container: name the container that answers every other path" if name.nil?
+
+            known_container!(:default_container, check(:default_container, name, NAME), containers)
+          end
+
+          def known_container!(key, name, containers)
+            return name if containers.any? { |c| c.name == name }
+
+            raise ArgumentError, "#{key}: #{name.inspect} is not a declared container"
+          end
+
+          def read_origin(settings)
+            header = settings[:origin_header]
+            secret = settings[:origin_secret]
+            return [nil, nil] if header.nil? && secret.nil?
+            raise ArgumentError, ORIGIN_PAIR if header.nil? || secret.nil?
+
+            [check(:origin_header, header, HEADER), check(:origin_secret, secret, SECRET_NAME)]
+          end
+
+          # `tunnel true` only opens the outbound port; a hash also runs cloudflared as a service.
+          #
+          # @param value [Boolean, Hash{Symbol => Object}] the world's `tunnel` setting
+          # @param containers [Array<Container>] the declared containers
+          # @return [Array(Boolean, Tunnel)] whether the egress opens, and the service if one runs
+          def read_tunnel(value, containers)
+            return [boolean(:tunnel, value), nil] unless value.is_a?(Hash)
+
+            to = value.fetch(:to) { raise ArgumentError, TUNNEL_SHAPE }
+            target = known_container!(:tunnel, check(:tunnel_to, to, NAME), containers)
+            token = check(:tunnel_token_secret, value.fetch(:token_secret) { raise ArgumentError, TUNNEL_SHAPE }, SECRET_NAME)
+            image = check(:tunnel_image, value.fetch(:image, TUNNEL_IMAGE), IMAGE)
+            port = containers.find { |c| c.name == target }.port
+            [true, Tunnel.new(container: target, port: port, token_secret: token, image: image)]
+          end
+
+          def read_prefixes(settings, infra_name)
+            list = Array(settings.fetch(:secret_prefixes, ["#{infra_name}/*"]))
+            list.map { |p| check(:secret_prefixes, p, SECRET_NAME) }
+          end
+
+          def string_map(key, value, key_pattern, value_pattern)
+            raise ArgumentError, "#{key}: expected a hash" unless value.is_a?(Hash)
+
+            value.to_h { |k, v| [check(key, k.to_s, key_pattern), check(key, v.to_s, value_pattern)] }
+          end
+
+          def check(key, value, pattern)
+            return value if value.is_a?(String) && value.match?(pattern)
+
+            raise ArgumentError, "#{key}: #{value.inspect} does not match #{pattern.inspect}"
+          end
+
+          def integer(key, value, low, high)
+            return value if value.is_a?(Integer) && value.between?(low, high)
+
+            raise ArgumentError, "#{key}: #{value.inspect} must be an integer from #{low} to #{high}"
+          end
+
+          def boolean(key, value)
+            return value if [true, false].include?(value)
+
+            raise ArgumentError, "#{key}: #{value.inspect} must be true or false"
+          end
+
+          def missing_containers
+            <<~MSG
+              deployed_to("AwsBox") needs at least one container. Add one, e.g.:
+
+                  deployed_to("AwsBox") do
+                    region "us-east-1"
+                    containers [{ name: "web", port: 8080 }]
+                  end
+            MSG
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projections/deploy/box/templates/box.yaml.tmpl

@@ -0,0 +1,267 @@
+AWSTemplateFormatVersion: "2010-09-09"
+Description: >
+  One EC2 box that runs @@STACK@@'s containers with Docker Compose behind Caddy, reading the RDS
+  instance from rds.yaml. No inbound rules but an optional CDN prefix list on port 80; use SSM Session
+  Manager to reach it. Secrets are read from Secrets Manager on the box at deploy time.
+
+Parameters:
+  VpcId:
+    Type: AWS::EC2::VPC::Id
+  SubnetId:
+    Type: AWS::EC2::Subnet::Id
+    Description: A public subnet. The box needs a public IP to reach ECR and Secrets Manager.
+  DbSecurityGroupId:
+    Type: AWS::EC2::SecurityGroup::Id
+    Description: DbSecurityGroupId output of the RDS stack.
+  DbSecretArn:
+    Type: String
+    Description: DbSecretArn output of the RDS stack.
+  InstanceType:
+    Type: String
+    Default: @@INSTANCE_TYPE@@
+  AmiId:
+    Type: AWS::SSM::Parameter::Value<AWS::EC2::Image::Id>
+    Default: @@AMI_PARAMETER@@
+    Description: Never re-resolve this on a live box, because a newer image replaces the instance.
+  RootVolumeGb:
+    Type: Number
+    Default: @@VOLUME_GB@@
+  AlertTopicArn:
+    Type: String
+    Default: ""
+    Description: AlertTopicArn output of the RDS stack. Blank creates the alarms with no notification target.
+  CdnPrefixListId:
+    Type: String
+    Default: ""
+    Description: >
+      A managed prefix list of the CDN's origin-facing addresses. When set, port 80 is open to it (the
+      proxy still refuses requests without the origin secret). Blank leaves the box with no inbound at all.
+  Rehearsal:
+    Type: String
+    Default: "false"
+    AllowedValues: ["true", "false"]
+    Description: true is a throwaway box with no Elastic IP.
+
+Conditions:
+  HasPrefixList: !Not [!Equals [!Ref CdnPrefixListId, ""]]
+  HasAlerts: !Not [!Equals [!Ref AlertTopicArn, ""]]
+  IsProduction: !Equals [!Ref Rehearsal, "false"]
+
+Resources:
+  BoxSecurityGroup:
+    Type: AWS::EC2::SecurityGroup
+    Properties:
+      GroupDescription: @@STACK@@ app box, port 80 from the CDN only, egress to RDS and 443
+      VpcId: !Ref VpcId
+      SecurityGroupIngress:
+        - !If
+          - HasPrefixList
+          - IpProtocol: tcp
+            FromPort: 80
+            ToPort: 80
+            SourcePrefixListId: !Ref CdnPrefixListId
+            Description: CDN origin-facing addresses
+          - !Ref AWS::NoValue
+      SecurityGroupEgress:
+        - IpProtocol: tcp
+          FromPort: 5432
+          ToPort: 5432
+          DestinationSecurityGroupId: !Ref DbSecurityGroupId
+        - IpProtocol: tcp
+          FromPort: 443
+          ToPort: 443
+          CidrIp: 0.0.0.0/0
+@@TUNNEL_EGRESS@@
+  BoxToDbIngress:
+    Type: AWS::EC2::SecurityGroupIngress
+    Properties:
+      GroupId: !Ref DbSecurityGroupId
+      IpProtocol: tcp
+      FromPort: 5432
+      ToPort: 5432
+      SourceSecurityGroupId: !Ref BoxSecurityGroup
+      Description: App box
+
+  BoxRole:
+    Type: AWS::IAM::Role
+    Properties:
+      AssumeRolePolicyDocument:
+        Version: "2012-10-17"
+        Statement:
+          - Effect: Allow
+            Principal: { Service: ec2.amazonaws.com }
+            Action: sts:AssumeRole
+      ManagedPolicyArns:
+        - !Sub arn:${AWS::Partition}:iam::aws:policy/AmazonSSMManagedInstanceCore
+        - !Sub arn:${AWS::Partition}:iam::aws:policy/AmazonEC2ContainerRegistryReadOnly
+      Policies:
+        - PolicyName: read-secrets
+          PolicyDocument:
+            Version: "2012-10-17"
+            Statement:
+              - Effect: Allow
+                Action: secretsmanager:GetSecretValue
+                Resource:
+                  - !Ref DbSecretArn
+@@SECRET_RESOURCES@@
+
+  BoxProfile:
+    Type: AWS::IAM::InstanceProfile
+    Properties:
+      Roles: [!Ref BoxRole]
+
+  Box:
+    Type: AWS::EC2::Instance
+    Properties:
+      ImageId: !Ref AmiId
+      InstanceType: !Ref InstanceType
+      SubnetId: !Ref SubnetId
+      SecurityGroupIds: [!Ref BoxSecurityGroup]
+      IamInstanceProfile: !Ref BoxProfile
+      BlockDeviceMappings:
+        - DeviceName: /dev/xvda
+          Ebs:
+            VolumeType: gp3
+            VolumeSize: !Ref RootVolumeGb
+            Encrypted: true
+            DeleteOnTermination: true
+      MetadataOptions:
+        HttpTokens: required
+        HttpPutResponseHopLimit: 2
+      Tags:
+        - Key: Name
+          Value: @@STACK@@-box
+        - Key: Backup
+          Value: @@STACK@@-box
+      UserData:
+        Fn::Base64: |
+          #!/bin/bash
+          set -eux
+          dnf install -y docker jq
+          systemctl enable --now docker
+          mkdir -p /usr/local/lib/docker/cli-plugins
+          curl -fsSL https://github.com/docker/compose/releases/download/v2.29.7/docker-compose-linux-$(uname -m) \
+            -o /usr/local/lib/docker/cli-plugins/docker-compose
+          chmod +x /usr/local/lib/docker/cli-plugins/docker-compose
+@@SWAP_COMMANDS@@          mkdir -p /opt/@@STACK@@
+
+  # Production only. A CDN needs an origin DNS name that survives a stop and start; an Elastic IP
+  # keeps the instance's public DNS name stable.
+  BoxAddress:
+    Type: AWS::EC2::EIP
+    Condition: IsProduction
+    Properties:
+      Domain: vpc
+      Tags:
+        - Key: Name
+          Value: @@STACK@@-box
+
+  BoxAddressAssociation:
+    Type: AWS::EC2::EIPAssociation
+    Condition: IsProduction
+    Properties:
+      AllocationId: !GetAtt BoxAddress.AllocationId
+      InstanceId: !Ref Box
+
+  # Daily snapshot of every volume on the instance. The database has its own RDS backups; this makes
+  # rebuilding the box fast.
+  SnapshotRole:
+    Type: AWS::IAM::Role
+    Properties:
+      AssumeRolePolicyDocument:
+        Version: "2012-10-17"
+        Statement:
+          - Effect: Allow
+            Principal: { Service: dlm.amazonaws.com }
+            Action: sts:AssumeRole
+      ManagedPolicyArns:
+        - !Sub arn:${AWS::Partition}:iam::aws:policy/service-role/AWSDataLifecycleManagerServiceRole
+
+  SnapshotPolicy:
+    Type: AWS::DLM::LifecyclePolicy
+    Properties:
+      # DLM allows only letters, digits, spaces, underscores and hyphens here.
+      Description: Daily snapshots of the @@STACK@@ app box - keep @@SNAPSHOTS_KEEP@@
+      State: ENABLED
+      ExecutionRoleArn: !GetAtt SnapshotRole.Arn
+      PolicyDetails:
+        ResourceTypes: [INSTANCE]
+        TargetTags:
+          - Key: Backup
+            Value: @@STACK@@-box
+        Schedules:
+          - Name: daily
+            CopyTags: true
+            CreateRule:
+              Interval: 24
+              IntervalUnit: HOURS
+              Times: ["07:00"]
+            RetainRule:
+              Count: @@SNAPSHOTS_KEEP@@
+
+  # A hardware fault on the host: EC2 moves the instance to healthy hardware (same disk, same
+  # address) and the topic is told.
+  SystemStatusAlarm:
+    Type: AWS::CloudWatch::Alarm
+    Properties:
+      AlarmDescription: EC2 system status check failing, recovering the instance
+      Namespace: AWS/EC2
+      MetricName: StatusCheckFailed_System
+      Dimensions: [{ Name: InstanceId, Value: !Ref Box }]
+      Statistic: Maximum
+      Period: 60
+      EvaluationPeriods: 2
+      Threshold: 0
+      ComparisonOperator: GreaterThanThreshold
+      TreatMissingData: notBreaching
+      AlarmActions: !If
+        - HasAlerts
+        - [!Ref AlertTopicArn, !Sub "arn:${AWS::Partition}:automate:${AWS::Region}:ec2:recover"]
+        - [!Sub "arn:${AWS::Partition}:automate:${AWS::Region}:ec2:recover"]
+
+  # The OS or networking inside the instance is unhealthy. Not auto-fixed: a reboot can lose state
+  # worth looking at.
+  InstanceStatusAlarm:
+    Type: AWS::CloudWatch::Alarm
+    Condition: HasAlerts
+    Properties:
+      AlarmDescription: EC2 instance status check failing for 5 minutes
+      Namespace: AWS/EC2
+      MetricName: StatusCheckFailed_Instance
+      Dimensions: [{ Name: InstanceId, Value: !Ref Box }]
+      Statistic: Maximum
+      Period: 60
+      EvaluationPeriods: 5
+      Threshold: 0
+      ComparisonOperator: GreaterThanThreshold
+      TreatMissingData: notBreaching
+      AlarmActions: [!Ref AlertTopicArn]
+      OKActions: [!Ref AlertTopicArn]
+
+  CpuHighAlarm:
+    Type: AWS::CloudWatch::Alarm
+    Condition: HasAlerts
+    Properties:
+      AlarmDescription: "Box CPU above 80% for 30 minutes"
+      Namespace: AWS/EC2
+      MetricName: CPUUtilization
+      Dimensions: [{ Name: InstanceId, Value: !Ref Box }]
+      Statistic: Average
+      Period: 300
+      EvaluationPeriods: 6
+      Threshold: 80
+      ComparisonOperator: GreaterThanThreshold
+      TreatMissingData: notBreaching
+      AlarmActions: [!Ref AlertTopicArn]
+      OKActions: [!Ref AlertTopicArn]
+@@ECR_REPOSITORIES@@
+Outputs:
+  InstanceId:
+    Value: !Ref Box
+  AppOriginDomain:
+    Condition: IsProduction
+    Description: The box's stable public DNS name, for a CDN's origin.
+    Value: !Join ["", ["ec2-", !Join ["-", !Split [".", !Ref BoxAddress]], ".@@COMPUTE_DOMAIN@@"]]
+  BoxSecurityGroupId:
+    Value: !Ref BoxSecurityGroup
+@@ECR_OUTPUTS@@

data/lib/hecks/projections/deploy/box/templates/deploy-box.sh.tmpl

@@ -0,0 +1,70 @@
+#!/bin/bash
+# Roll @@STACK@@'s app box: render the compose files, push them over SSM, start the containers and check
+# them. Exits non-zero if the roll fails or the box does not answer as expected.
+#
+#   deploy-box.sh [name=tag ...]
+#
+# A container named without a tag runs its "latest" image. Secret values are resolved on the box by
+# fetch-secrets.sh and never pass through the SSM command.
+set -euo pipefail
+HERE=$(cd "$(dirname "$0")" && pwd)
+BOX_STACK=@@BOX_STACK@@
+RDS_STACK=@@RDS_STACK@@
+REGION=@@REGION@@
+DIR=/opt/@@STACK@@
+out() { aws cloudformation describe-stacks --stack-name "$1" --query "Stacks[0].Outputs[?OutputKey==\`$2\`].OutputValue" --output text; }
+
+BOX=$(out "$BOX_STACK" InstanceId)
+DB_HOST=$(out "$RDS_STACK" DbEndpoint)
+DB_SECRET=$(out "$RDS_STACK" DbSecretArn)
+[ -n "$BOX" ] && [ "$BOX" != None ] || { echo "no instance in stack $BOX_STACK" >&2; exit 1; }
+ACCOUNT=$(aws sts get-caller-identity --query Account --output text)
+
+WORK=$(mktemp -d); trap 'rm -rf "$WORK"' EXIT
+( cd "$WORK" && bash "$HERE/render-compose.sh" "$DB_HOST" "$DB_SECRET" "$@" )
+
+# Run a script on the box over SSM, wait for it, print its output, return its status.
+run_on_box() {
+  local cid st i
+  cid=$(aws ssm send-command --instance-ids "$BOX" --document-name AWS-RunShellScript --timeout-seconds 900 \
+    --parameters "$1" --query 'Command.CommandId' --output text)
+  sleep 3
+  for i in $(seq 1 150); do
+    st=$(aws ssm get-command-invocation --command-id "$cid" --instance-id "$BOX" --query Status --output text)
+    [ "$st" != InProgress ] && [ "$st" != Pending ] && break
+    sleep 5
+  done
+  aws ssm get-command-invocation --command-id "$cid" --instance-id "$BOX" --query StandardOutputContent --output text
+  [ "$st" = Success ]
+}
+
+B64() { base64 < "$1" | tr -d '\n'; }
+ROLL=$(jq -n --arg compose "$(B64 "$WORK/compose.json")" --arg secrets "$(B64 "$WORK/secrets.json")" \
+  --arg caddy "$(B64 "$HERE/Caddyfile")" --arg fetch "$(B64 "$HERE/fetch-secrets.sh")" \
+  --arg registry "$ACCOUNT.dkr.ecr.$REGION.amazonaws.com" --arg dir "$DIR" '
+  {commands: ["set -e", "mkdir -p \($dir) && cd \($dir)", "umask 077",
+    "echo \($compose) | base64 -d > compose.json; echo \($secrets) | base64 -d > secrets.json",
+    "echo \($caddy) | base64 -d > Caddyfile; echo \($fetch) | base64 -d > fetch-secrets.sh",
+    "bash fetch-secrets.sh",
+    "aws ecr get-login-password --region '"$REGION"' | docker login --username AWS --password-stdin \($registry) >/dev/null",
+    "docker compose -f compose.json pull --quiet",
+    "docker compose -f compose.json up -d --remove-orphans",
+    "sleep 20; docker compose -f compose.json ps --format \"table {{.Service}}\\t{{.Status}}\""],
+   executionTimeout: ["900"]}')
+
+echo "==> rolling $BOX_STACK ($BOX) at $(date -u +%H:%M:%SZ)"
+run_on_box "$ROLL" || { echo "==> the roll did not succeed" >&2; exit 1; }
+
+echo "==> checking the box"
+CHECK=$(cat <<'CHECK_EOF'
+cd @@DIR@@
+BAD=0
+@@HEALTH_CHECKS@@
+DOWN=$(docker compose -f compose.json ps --format "{{.Service}} {{.Status}}" | grep -vE " Up " || true)
+if [ -z "$DOWN" ]; then echo "ok   every container is up"; else echo "FAIL containers not up: $DOWN"; BAD=1; fi
+[ "$BAD" = 0 ]
+CHECK_EOF
+)
+CHECK_JSON=$(jq -n --arg c "$(printf '%s' "$CHECK" | base64 | tr -d '\n')" '{commands: ["echo \($c) | base64 -d | bash"]}')
+run_on_box "$CHECK_JSON" || { echo "==> the box is NOT healthy after the roll" >&2; exit 1; }
+echo "==> box roll done ($(date -u +%H:%M:%SZ))"

data/lib/hecks/projections/deploy/box/templates/fetch-secrets.sh

@@ -0,0 +1,21 @@
+#!/bin/bash
+# Runs ON the box. Resolves secrets.json into per-service env files that compose reads, using the
+# instance role, so secret values never pass through SSM command text.
+#
+# secrets.json: [{"service":"web","name":"AUTH_SECRET","valueFrom":"myapp/auth"}]
+# valueFrom is a secret name (its whole string is the value) or a full ARN, optionally with a JSON
+# key (arn:...:secret:NAME:jsonkey::) to pick one field of a JSON secret.
+set -eu
+cd "$(dirname "$0")"
+umask 077
+rm -f ./*.secrets.env
+jq -r '.[] | [.service, .name, .valueFrom] | @tsv' secrets.json | while IFS=$'\t' read -r svc name from; do
+  case "$from" in
+    arn:*) id=$(echo "$from" | cut -d: -f1-7); region=$(echo "$from" | cut -d: -f4); jkey=$(echo "$from" | cut -d: -f8) ;;
+    *) id=$from; region=""; jkey="" ;;
+  esac
+  val=$(aws secretsmanager get-secret-value ${region:+--region "$region"} --secret-id "$id" --query SecretString --output text)
+  if [ -n "$jkey" ]; then val=$(printf %s "$val" | jq -r --arg k "$jkey" '.[$k]'); fi
+  [ -n "$val" ] && [ "$val" != null ] || { echo "empty secret for $svc/$name" >&2; exit 1; }
+  printf '%s=%s\n' "$name" "$val" >> "$svc.secrets.env"
+done