hecks 3.4.2 → 3.6.0

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

@@ -1,4 +1,9 @@
 require_relative "hosting_settings"
+require_relative "settings/patterns"
+require_relative "settings/types"
+require_relative "settings/checks"
+require_relative "settings/containers"
+require_relative "settings/origin"
 
 module Hecks
   module Projections
@@ -11,94 +16,11 @@ module Hecks
         # 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}
-          TASKDEF     = /\A[a-zA-Z0-9_-]{1,255}\z/
-          SCHEMA      = /\A[a-z][a-z0-9_]{0,62}\z/
-          MIGRATION_SHAPE = "migration: a hash needs `schemas`, a list of the schema names to copy".freeze
-          S3_BUCKET   = /\A[a-z0-9][a-z0-9.-]{1,61}[a-z0-9]\z/
-          S3_SHAPE    = "s3_access: a list of `{ bucket: \"name\", write: true }` hashes (write is optional)".freeze
-          FROM_TASKDEF = %i[env secrets repository].freeze
-          # 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_ENV_SHAPE = "origin_env: the container environment variable names that hold the origin secret " \
-                             "need an origin_secret and a task_definition to compare against".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
-          # @!attribute [r] tag_parameter [String] the stack parameter that holds this container's
-          #   image tag, which a hosting `deploy-service.sh` sets
-          Container = Struct.new(:name, :repository, :port, :env, :secrets, :tag_parameter, 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)
-
-          # The data a project moves from its old database into the new RDS instance.
-          #
-          # @!attribute [r] schemas [Array<String>] the schemas to copy
-          # @!attribute [r] database [String] the database holding them on the RDS instance
-          # @!attribute [r] source_database [String] the database holding them on the old server
-          Migration = Struct.new(:schemas, :database, :source_database, keyword_init: true)
-
-          # An S3 bucket the box's role may read, and in production write.
-          #
-          # @!attribute [r] name [String] the bucket's name
-          # @!attribute [r] write [Boolean] whether a production box may also write and delete
-          Bucket = Struct.new(:name, :write, 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, :writable_secrets, :origin_env, :tunnel, :tunnel_service, :proxy_image, :task_definition,
-            :migration, :s3_buckets, :hosting, 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
+          include Patterns
+          include Types
+          extend Checks
+          extend ContainerReaders
+          extend OriginReaders
 
           module_function
 
@@ -115,24 +37,44 @@ module Hecks
             listed = s.fetch(:containers) { raise ArgumentError, missing_containers }
             task_definition = read_task_definition(s[:task_definition], listed)
             containers = read_containers(listed, infra_name)
-            header, secret = read_origin(s)
-            origin_env = read_origin_env(s, secret, task_definition)
-            tunnel, tunnel_service = read_tunnel(s.fetch(:tunnel, false), containers)
+            edge = edge_fields(s, containers, task_definition)
+            Plan.new(**plan_fields(s, target, infra_name, database_name, containers), **edge,
+                     **extra_fields(s, task_definition, database_name))
+          end
+
+          # @return [Hash{Symbol => Object}] the task definition, the migration, S3 access and
+          #   hosting
+          def extra_fields(settings, task_definition, database_name)
+            {
+              task_definition: task_definition, migration: read_migration(settings[:migration], database_name),
+              s3_buckets: read_s3_access(settings.fetch(:s3_access, [])),
+              hosting: HostingSettings.read(settings, task_definition)
+            }
+          end
+
+          # @param settings [Hash{Symbol => Object}] the world's `AwsBox` settings
+          # @param containers [Array<Container>] the declared containers
+          # @param task_definition [String, nil] the declared task definition family
+          # @return [Hash{Symbol => Object}] the origin guard and the tunnel
+          def edge_fields(settings, containers, task_definition)
+            header, secret = read_origin(settings)
+            origin_env = read_origin_env(settings, secret, task_definition)
+            tunnel, tunnel_service = read_tunnel(settings.fetch(:tunnel, false), containers)
+            { origin_header: header, origin_secret: secret, origin_env: origin_env,
+              tunnel: tunnel, tunnel_service: tunnel_service }
+          end
 
-            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: database_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, origin_env: origin_env, secret_prefixes: read_prefixes(s, infra_name),
-              writable_secrets: read_writable_secrets(s),
-              tunnel: tunnel, tunnel_service: tunnel_service,
-              proxy_image: check(:proxy_image, s.fetch(:proxy_image, PROXY_IMAGE), IMAGE),
-              task_definition: task_definition, migration: read_migration(s[:migration], database_name),
-              s3_buckets: read_s3_access(s.fetch(:s3_access, [])),
-              hosting: HostingSettings.read(s, task_definition)
-            )
+          # @return [Hash{Symbol => Object}] the plan's names, sizes, routes and secret scopes
+          def plan_fields(settings, target, infra_name, database_name, containers)
+            {
+              infra_name: infra_name, stack_prefix: check(:stack_prefix, settings.fetch(:stack_prefix, "hecks"), PREFIX),
+              **declared_sizes(target), **read_sizes(settings), database_name: database_name,
+              engine_version: check(:engine_version, settings.fetch(:engine_version, "16").to_s, ENGINE),
+              containers: containers, routes: read_routes(settings.fetch(:routes, []), containers),
+              default_container: read_default(settings[:default_container], containers),
+              secret_prefixes: read_prefixes(settings, infra_name), writable_secrets: read_writable_secrets(settings),
+              proxy_image: check(:proxy_image, settings.fetch(:proxy_image, PROXY_IMAGE), IMAGE)
+            }
           end
 
           # @param target [Object] the declared `BoxTarget`
@@ -157,14 +99,20 @@ module Hecks
           # @raise [ArgumentError] when the setting is not a hash with a non-empty list of schemas
           def read_migration(value, database_name)
             return nil if value.nil?
+
+            listed = migration_schemas(value)
+            database = check(:migration_database, value.fetch(:database, database_name), DB_NAME)
+            Migration.new(schemas: listed.map { |name| check(:migration_schemas, name, SCHEMA) }.uniq, database: database,
+                          source_database: check(:migration_source_database, value.fetch(:source_database, database), DB_NAME))
+          end
+
+          def migration_schemas(value)
             raise ArgumentError, MIGRATION_SHAPE unless value.is_a?(Hash)
 
             listed = value.fetch(:schemas) { raise ArgumentError, MIGRATION_SHAPE }
             raise ArgumentError, MIGRATION_SHAPE unless listed.is_a?(Array) && !listed.empty?
 
-            database = check(:migration_database, value.fetch(:database, database_name), DB_NAME)
-            Migration.new(schemas: listed.map { |name| check(:migration_schemas, name, SCHEMA) }.uniq, database: database,
-                          source_database: check(:migration_source_database, value.fetch(:source_database, database), DB_NAME))
+            listed
           end
 
           # @param list [Array<Hash>] the world's `s3_access` setting
@@ -200,164 +148,11 @@ module Hecks
               clash = spec.is_a?(Hash) ? FROM_TASKDEF & spec.keys : []
               next if clash.empty?
 
-              raise ArgumentError, "containers: #{spec[:name]} sets #{clash.join(', ')}, which the task definition " \
-                                   "#{family} supplies; drop #{clash.size == 1 ? 'it' : 'them'} or drop task_definition"
+              raise ArgumentError, "containers: #{spec[:name]} sets #{clash.join(", ")}, which the task definition " \
+                                   "#{family} supplies; drop #{clash.size == 1 ? "it" : "them"} or drop task_definition"
             end
             family
           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),
-              tag_parameter: check(:tag_parameter, spec.fetch(:tag_parameter, default_tag_parameter(name)),
-                                   HostingSettings::PARAMETER)
-            )
-          end
-
-          # @param name [String] a container name such as `web-app`
-          # @return [String] the image-tag parameter a stack names it by, such as `WebAppImageTag`
-          def default_tag_parameter(name)
-            "#{name.split('-').map(&:capitalize).join}ImageTag"
-          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
-
-          # The container environment variables that hold the origin secret in the task
-          # definition. Only Caddy reads the named secret; the containers keep the task
-          # definition's copy, so a copy that differs makes every request through the CDN
-          # fail. Naming them lets deploy refuse a mismatch.
-          #
-          # @param settings [Hash{Symbol => Object}] the world's `AwsBox` settings
-          # @param secret [String, nil] the declared origin secret
-          # @param task_definition [String, nil] the declared task definition family
-          # @return [Array<String>] the variable names, empty when none are declared
-          # @raise [ArgumentError] when named without an origin secret and a task definition
-          def read_origin_env(settings, secret, task_definition)
-            names = Array(settings.fetch(:origin_env, []))
-            return [] if names.empty?
-            raise ArgumentError, ORIGIN_ENV_SHAPE if secret.nil? || task_definition.nil?
-
-            names.map { |name| check(:origin_env, name, ENV_KEY) }.uniq
-          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
-
-          # Secrets the box may overwrite, such as one an admin page stores a key in. Production
-          # only: a rehearsal box never changes a secret.
-          def read_writable_secrets(settings)
-            Array(settings.fetch(:writable_secrets, [])).map { |name| check(:writable_secrets, name, 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

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

@@ -0,0 +1,107 @@
+module Hecks
+  module Projections
+    module Deploy
+      module Box
+        # The two CloudFormation stacks of a box deploy, and the pieces spliced into them. Mixed
+        # into `Box`, which supplies `template`, the access statements and the constants.
+        module StackYaml
+          # @param plan [Settings::Plan] the resolved settings
+          # @return [String] the database stack
+          def rds_yaml(plan)
+            template("rds.yaml.tmpl", "STACK" => plan.infra_name, "DB_CLASS" => plan.database_class,
+                                      "STORAGE_GB" => plan.storage_gb.to_s, "DB_NAME" => plan.database_name,
+                                      "ENGINE_VERSION" => plan.engine_version, "BACKUP_DAYS" => plan.backup_days.to_s)
+          end
+
+          # @param plan [Settings::Plan] the resolved settings
+          # @param region [String] the validated region
+          # @return [String] the box stack
+          def box_yaml(plan, region)
+            template("box.yaml.tmpl",
+                     "STACK" => plan.infra_name, "INSTANCE_TYPE" => plan.instance_type,
+                     "VOLUME_GB" => plan.volume_gb.to_s, "SNAPSHOTS_KEEP" => plan.snapshots_keep.to_s,
+                     "AMI_PARAMETER" => ami_parameter(plan.instance_type),
+                     "COMPUTE_DOMAIN" => compute_domain(region),
+                     "SECRET_RESOURCES" => secret_resources(plan), "WRITABLE_SECRETS" => writable_secrets(plan),
+                     "TUNNEL_EGRESS" => tunnel_egress(plan),
+                     "SWAP_COMMANDS" => swap_commands(plan), "ECR_REPOSITORIES" => ecr_repositories(plan),
+                     "ECR_OUTPUTS" => ecr_outputs(plan), "S3_POLICY" => s3_policy(plan))
+          end
+
+          # Graviton families end their generation digit with `g` (`t4g`, `m7gd`, `c6gn`).
+          #
+          # @param instance_type [String] an EC2 instance type
+          # @return [String] the SSM parameter of the matching Amazon Linux image
+          def ami_parameter(instance_type)
+            arch = instance_type.split(".").first.match?(/\d+g[a-z]*\z/) ? "arm64" : "x86_64"
+            "/aws/service/ami-amazon-linux-latest/al2023-ami-kernel-default-#{arch}"
+          end
+
+          # @param region [String] the AWS region
+          # @return [String] the DNS suffix an Elastic address's public name ends with
+          def compute_domain(region)
+            region == LEGACY_COMPUTE_REGION ? "compute-1.amazonaws.com" : "#{region}.compute.amazonaws.com"
+          end
+
+          # @param plan [Settings::Plan] the resolved settings
+          # @return [String] the outbound rules a Cloudflare Tunnel sidecar needs, or nothing
+          def tunnel_egress(plan)
+            return "" unless plan.tunnel
+
+            template("tunnel-egress.yaml.tmpl", {})
+          end
+
+          # @param plan [Settings::Plan] the resolved settings
+          # @return [String] the user-data lines that add swap, or nothing when `swap_gb` is 0
+          def swap_commands(plan)
+            return "" if plan.swap_gb.zero?
+
+            pad = " " * 10
+            <<~SH.lines.map { |line| "#{pad}#{line}" }.join
+              # swap so a memory spike at boot cannot take the box down
+              fallocate -l #{plan.swap_gb}G /swapfile && chmod 600 /swapfile && mkswap /swapfile && swapon /swapfile
+              echo '/swapfile none swap sw 0 0' >> /etc/fstab
+            SH
+          end
+
+          # One ECR repository per container, keeping the newest 30 images. A task definition names
+          # images that already have repositories, so none are made.
+          #
+          # @param plan [Settings::Plan] the resolved settings
+          # @return [String] CloudFormation resources, each preceded by a blank line
+          def ecr_repositories(plan)
+            return "" if plan.task_definition
+
+            plan.containers.map do |container|
+              ecr_repository(container).lines.map { |line| line.strip.empty? ? line : "  #{line}" }.join
+            end.join.chomp
+          end
+
+          # @param plan [Settings::Plan] the resolved settings
+          # @return [String] one repository URI output per container
+          def ecr_outputs(plan)
+            return "" if plan.task_definition
+
+            plan.containers.map do |container|
+              id = logical(container.name)
+              "  #{id}RepositoryUri:\n    Value: !GetAtt #{id}Repository.RepositoryUri\n"
+            end.join.chomp
+          end
+
+          # @param name [String] a container name such as `web-app`
+          # @return [String] a CloudFormation logical id fragment, such as `WebApp`
+          def logical(name)
+            name.split("-").map(&:capitalize).join
+          end
+
+          private
+
+          def ecr_repository(container)
+            template("ecr-repository.yaml.tmpl", "ID"         => "#{logical(container.name)}Repository",
+                                                 "REPOSITORY" => container.repository)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projections/deploy/box/templates/MIGRATION.md.tmpl

@@ -0,0 +1,39 @@
+# Moving @@STACK@@ onto the box and RDS
+
+Generated from the world's `migration` setting. Nothing here has been run for you.
+
+Schemas to copy: @@SCHEMA_LIST@@, in database
+`@@SOURCE_DATABASE@@` on the old server and `@@DATABASE@@` on RDS.
+
+## Before cutover
+
+1. Create the stacks: `make stacks VPC=... PRIVATE_SUBNETS=... PUBLIC_SUBNET=...`. To rehearse first,
+   deploy `rds.yaml` and `box.yaml` under other stack names with `Rehearsal=true`: the database is then
+   deleted with its stack and the box gets no stable public address. Delete the rehearsal stacks after.
+2. Copy the data. The bastion is any instance that can reach both databases.
+
+   ```
+   RDS_HOST=$(aws cloudformation describe-stacks --stack-name @@RDS_STACK@@ --query "Stacks[0].Outputs[?OutputKey=='DbEndpoint'].OutputValue" --output text)
+   RDS_SECRET=$(aws cloudformation describe-stacks --stack-name @@RDS_STACK@@ --query "Stacks[0].Outputs[?OutputKey=='DbSecretArn'].OutputValue" --output text)
+   bash restore-to-rds.sh <bastion-instance-id> <old-host> <old-secret-arn> "$RDS_HOST" "$RDS_SECRET"
+   ```
+
+   It copies each schema, refreshes the materialized views a plain `pg_restore` cannot, then runs
+   `verify-copy.sh`, which compares structure and the exact row count of every table and prints `OK`
+   only if both match. Re-run with `FORCE=1` to reload.
+3. Deploy the app onto the box: `@@DEPLOY@@`. The deploy ends with health checks on the box.
+4. Run the project's own smoke test against the box before any traffic moves.
+
+## Cutover
+
+1. Stop writes on the old stack, then run `restore-to-rds.sh` again with `FORCE=1` for a final copy and
+   wait for `OK`.
+2. Point the CDN's origin at the box stack's `AppOriginDomain` output.
+3. Keep the old database untouched for several days, and take a final snapshot before deleting it.
+
+## Rollback
+
+Until the first write lands on RDS, point the origin back. After that, writes taken by both databases
+cannot be merged: choose one side and copy it over the other (swap the hosts and secrets, and set
+`SRC_DB` and `DST_DB`, with `FORCE=1`). Do not change the domain's era in the same window, so a rollback
+only has to move data.

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

@@ -0,0 +1,24 @@
+# @@STACK@@: one app box and one RDS instance.
+#   make stacks VPC=vpc-... PRIVATE_SUBNETS=subnet-a,subnet-b PUBLIC_SUBNET=subnet-c [REHEARSAL=true]
+#   make deploy @@DEPLOY_HINT@@
+RDS_STACK = @@RDS_STACK@@
+BOX_STACK = @@BOX_STACK@@
+# true makes a throwaway pair: the database is deleted with its stack and the box has no
+# Elastic IP. The default is a production pair, with deletion protection.
+REHEARSAL ?= false
+
+HECKS ?= hecks
+
+.PHONY: stacks deploy
+stacks:
+	aws cloudformation deploy --template-file rds.yaml --stack-name $(RDS_STACK) --capabilities CAPABILITY_IAM \
+		--parameter-overrides VpcId=$(VPC) PrivateSubnetIds=$(PRIVATE_SUBNETS) Rehearsal=$(REHEARSAL)
+	aws cloudformation deploy --template-file box.yaml --stack-name $(BOX_STACK) --capabilities CAPABILITY_IAM \
+		--parameter-overrides VpcId=$(VPC) SubnetId=$(PUBLIC_SUBNET) \
+		DbSecurityGroupId=$$(aws cloudformation describe-stacks --stack-name $(RDS_STACK) --query "Stacks[0].Outputs[?OutputKey=='DbSecurityGroupId'].OutputValue" --output text) \
+		DbSecretArn=$$(aws cloudformation describe-stacks --stack-name $(RDS_STACK) --query "Stacks[0].Outputs[?OutputKey=='DbSecretArn'].OutputValue" --output text) \
+		AlertTopicArn=$$(aws cloudformation describe-stacks --stack-name $(RDS_STACK) --query "Stacks[0].Outputs[?OutputKey=='AlertTopicArn'].OutputValue" --output text) \
+		Rehearsal=$(REHEARSAL)
+
+deploy:
+@@DEPLOY_RECIPE@@

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

@@ -2,6 +2,19 @@
 # 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.
 #
+# Exit codes (the ones `hecks deploy box_roll.run` names; a step that fails under `set -e` ends with its
+# own status, 1 from bash and 254/255 from the aws CLI):
+#   0   the roll succeeded and the box answered healthy
+#   40  the box stack has no instance
+#   41  the roll did not succeed on the box
+#   42  the roll succeeded but the box is not healthy after it
+#
+# Before the roll replaces a container, the box saves that container's log to
+# /var/log/hecks-captures/<container>-<UTC timestamp>.log and keeps the newest 14 per container
+# (a roll deletes the old container's log with it). A capture never changes the exit codes: if it
+# cannot run, the roll goes on. SKIP_LOG_CAPTURE=1 skips it; LOG_CAPTURE_SERVICES="a b" limits it to
+# those services (deploy-service.sh sets the one it rolls).
+#
 @@USAGE@@
 set -euo pipefail
 HERE=$(cd "$(dirname "$0")" && pwd)
@@ -14,7 +27,7 @@ out() { aws cloudformation describe-stacks --stack-name "$1" --query "Stacks[0].
 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; }
+[ -n "$BOX" ] && [ "$BOX" != None ] || { echo "no instance in stack $BOX_STACK" >&2; exit 40; }
 ACCOUNT=$(aws sts get-caller-identity --query Account --output text)
 
 WORK=$(mktemp -d); trap 'rm -rf "$WORK"' EXIT
@@ -37,7 +50,7 @@ SMOKE_EOF
 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)
+    --parameters "$1" --query 'Command.CommandId' --output text) || return 1
   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)
@@ -67,8 +80,42 @@ ROLL=$(jq -n --arg compose "$(B64 "$WORK/compose.json")" --arg secrets "$(B64 "$
     "for i in $(seq 1 40); do docker compose -f compose.json ps --format \"{{.Status}}\" | grep -qE \"^Up (Less than a second|[0-4] seconds?)|Restarting|Created|Exited\" || break; sleep 1; done; docker compose -f compose.json ps --format \"table {{.Service}}\\t{{.Status}}\""],
    executionTimeout: ["900"]}')
 
+# Saves the log of each running container about to be replaced. It only reads containers and writes
+# files under /var/log/hecks-captures, skips on low disk, never prints a log's contents, and ends 0.
+CAPTURE=$(cat <<'CAPTURE_EOF'
+umask 027
+cd "${CAPTURE_HOME:-@@DIR@@}" 2>/dev/null && [ -f compose.json ] || { echo "log capture: no running roll to capture"; exit 0; }
+LOGDIR=${CAPTURE_DIR:-/var/log/hecks-captures}; KEEP=14
+FREE_KB=$(df -Pk "${CAPTURE_DF_PATH:-/var/log}" 2>/dev/null | awk 'NR==2 {print $4}')
+if [ "${FREE_KB:-0}" -lt "${CAPTURE_MIN_FREE_KB:-2097152}" ]; then
+  echo "WARNING log capture skipped: under 2 GiB free on /var/log"; exit 0
+fi
+mkdir -p "$LOGDIR" && chmod 750 "$LOGDIR" || { echo "WARNING log capture skipped: cannot create $LOGDIR"; exit 0; }
+STAMP=$(date -u +%Y%m%dT%H%M%SZ)
+docker compose -f compose.json ps --format '{{.Service}} {{.Name}}' 2>/dev/null | while read -r svc name; do
+  [ -z "$ONLY" ] || printf ' %s ' "$ONLY" | grep -qF " $svc " || continue
+  f="$LOGDIR/$name-$STAMP.log"
+  if docker logs "$name" > "$f" 2>&1 < /dev/null; then
+    chmod 640 "$f"; echo "captured $f $(wc -c < "$f" | tr -d ' ') bytes"
+  else
+    rm -f "$f"; echo "WARNING log capture failed for $name; the roll goes on"
+  fi
+  ls -1 "$LOGDIR/$name"-[0-9]*T[0-9]*Z.log 2>/dev/null | sort -r | tail -n +$((KEEP + 1)) | while read -r old; do rm -f "$old"; done
+done
+exit 0
+CAPTURE_EOF
+)
+if [ "${SKIP_LOG_CAPTURE:-}" = 1 ]; then
+  echo "==> skipping the log capture (SKIP_LOG_CAPTURE=1)"
+else
+  echo "==> capturing the logs of the containers about to be replaced"
+  ONLY=$(printf '%s' "${LOG_CAPTURE_SERVICES:-}" | tr -cd 'A-Za-z0-9_. -')
+  CAPTURE_JSON=$(jq -n --arg c "$(printf "ONLY='%s'\n%s\n" "$ONLY" "$CAPTURE" | base64 | tr -d '\n')" '{commands: ["echo \($c) | base64 -d | bash"]}')
+  run_on_box "$CAPTURE_JSON" || echo "WARNING the log capture could not run on the box; the roll goes on" >&2
+fi
+
 echo "==> rolling $BOX_STACK ($BOX) at $(date -u +%H:%M:%SZ)"
-run_on_box "$ROLL" || { echo "==> the roll did not succeed" >&2; exit 1; }
+run_on_box "$ROLL" || { echo "==> the roll did not succeed" >&2; exit 41; }
 
 echo "==> checking the box"
 CHECK=$(cat <<'CHECK_EOF'
@@ -81,5 +128,5 @@ if [ -z "$DOWN" ]; then echo "ok   every container is up"; else echo "FAIL conta
 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; }
+run_on_box "$CHECK_JSON" || { echo "==> the box is NOT healthy after the roll" >&2; exit 42; }
 echo "==> box roll done ($(date -u +%H:%M:%SZ))"

data/lib/hecks/projections/deploy/box/templates/deploy-service.services-roll.part

@@ -2,7 +2,7 @@
 # container runs now, read from the box's own Compose file, so rolling one service leaves the rest alone.
 BOX_ID="$(aws cloudformation describe-stacks --stack-name "$BOX_STACK" --region "$REGION" \
   --query "Stacks[0].Outputs[?OutputKey=='InstanceId'].OutputValue" --output text)"
-[ -n "$BOX_ID" ] && [ "$BOX_ID" != None ] || { echo "no instance in stack ${BOX_STACK}" >&2; exit 1; }
+[ -n "$BOX_ID" ] && [ "$BOX_ID" != None ] || { echo "no instance in stack ${BOX_STACK}" >&2; exit 33; }
 
 echo "==> reading the tags the box runs now"
 READ_JSON="$(jq -n --arg c "cat ${BOX_DIR}/compose.json 2>/dev/null || echo '{}'" '{commands: [$c]}')"
@@ -14,7 +14,7 @@ for _ in $(seq 1 30); do
     --query Status --output text 2>/dev/null || echo Pending)"
   [ "$state" != InProgress ] && [ "$state" != Pending ] && break
 done
-[ "$state" = Success ] || { echo "could not read the box's Compose file (${state}); nothing was rolled" >&2; exit 1; }
+[ "$state" = Success ] || { echo "could not read the box's Compose file (${state}); nothing was rolled" >&2; exit 32; }
 aws ssm get-command-invocation --command-id "$COMMAND_ID" --instance-id "$BOX_ID" --region "$REGION" \
   --query StandardOutputContent --output text > "${SCRATCH_DIR}/compose.json"
 
@@ -30,4 +30,5 @@ for name in $SERVICES; do
 done
 echo "==> rolling ${TAGS[*]}"
 
-bash ./deploy-box.sh "${TAGS[@]}"
+# Only this container is replaced, so only its log is captured first (SKIP_LOG_CAPTURE=1 skips it).
+LOG_CAPTURE_SERVICES="$SERVICE_NAME" bash ./deploy-box.sh "${TAGS[@]}"