hecks 3.11.0 → 3.12.0

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

@@ -0,0 +1,99 @@
+module Hecks
+  module Projections
+    module Deploy
+      module Box
+        # Where the box's containers write their logs. With `logs "cloudwatch"` (the default) every
+        # service uses Docker's `awslogs` driver into one log group the box stack creates, one
+        # stream per service, and the box role may write to that group only. With `logs "local"`
+        # the services keep Docker's rotating `json-file` logs, which a roll deletes with the
+        # container.
+        #
+        # `docker logs` keeps working with `awslogs`: Docker's dual-logging cache (Docker 20.10 and
+        # later, which the Amazon Linux 2023 package installs) keeps a local copy for reads.
+        # Mixed into `Box`, which supplies `template`.
+        module Logging
+          LOG_EXIT_CODE = "#   44  the box stack has no log group yet: update the stack (make stacks) before rolling\n".freeze
+          LOG_NOTE = <<~NOTE.freeze
+            # Every container logs to the CloudWatch group the box stack creates. A container whose log
+            # stream cannot be written does not start, so the roll first checks that the stack has the
+            # group (and the role's right to write it) and exits 44 if not. SKIP_LOG_GROUP_CHECK=1 skips it.
+            # `docker logs` and the log capture below still read the box's local copy (Docker's dual-logging cache).
+            #
+          NOTE
+          LOG_GROUP_CHECK = <<~CHECK.freeze
+            if [ "${SKIP_LOG_GROUP_CHECK:-}" = 1 ]; then
+              echo "==> skipping the log group check (SKIP_LOG_GROUP_CHECK=1)"
+            elif ! aws cloudformation describe-stack-resource --stack-name "$BOX_STACK" --logical-resource-id BoxLogGroup >/dev/null 2>&1; then
+              echo "==> $BOX_STACK has no BoxLogGroup: its containers would fail to start on the awslogs driver." >&2
+              echo "    Run make stacks to update box.yaml (log group and the role's logs policy) first, then roll again." >&2
+              exit 44
+            fi
+          CHECK
+          COMPOSE_LOG_NOTE = <<~NOTE.freeze
+            #
+            # Every service logs to the CloudWatch group the box stack creates (one stream per service). A
+            # container whose stream cannot be written does not start, so update the box stack (make stacks:
+            # the group and the role's logs policy) before the first roll that uses this file. `docker logs`
+            # still reads the box's local copy.
+          NOTE
+          JSON_FILE = '{driver: "json-file", options: {"max-size": "10m", "max-file": "3"}}'.freeze
+
+          # @param plan [Settings::Plan] the resolved settings
+          # @return [String] the log group resource spliced into `box.yaml`, or nothing for `local`
+          def log_group_yaml(plan)
+            return "" unless plan.cloudwatch_logs?
+
+            template("log-group.yaml.tmpl", "LOG_GROUP"      => plan.log_group,
+                                            "RETENTION_DAYS" => plan.log_retention_days.to_s)
+          end
+
+          # @param plan [Settings::Plan] the resolved settings
+          # @return [String] the role policy that lets the box write to its log group only, or
+          #   nothing for `local`
+          def log_policy_yaml(plan)
+            plan.cloudwatch_logs? ? template("log-policy.yaml.tmpl", {}) : ""
+          end
+
+          # The values `render-compose.sh` splices in: the jq definition of `log` and the call that
+          # names each service's stream. `local` renders the `json-file` definition and the bare
+          # `log`, so its output does not change.
+          #
+          # @param plan [Settings::Plan] the resolved settings
+          # @param region [String] the validated region
+          # @param service [String] the jq expression for a service's name in the template
+          # @return [Hash{String => String}] the template values
+          def compose_log_values(plan, region, service)
+            return { "COMPOSE_LOG_NOTE" => "", **local_log_values } unless plan.cloudwatch_logs?
+
+            { "COMPOSE_LOG_NOTE" => COMPOSE_LOG_NOTE, "LOG_DEF" => awslogs_definition(plan, region),
+              "LOG_SERVICE" => "log(#{service})", "LOG_CADDY" => 'log("caddy")', "LOG_TUNNEL" => 'log("cloudflared")' }
+          end
+
+          # The `deploy-box.sh` pieces that stop a roll onto a stack without the log group.
+          #
+          # @param plan [Settings::Plan] the resolved settings
+          # @return [Hash{String => String}] the exit-code line, the comment and the check, or empty
+          #   strings for `local`
+          def log_roll_values(plan)
+            return { "LOG_EXIT_CODE" => "", "LOG_NOTE" => "", "LOG_GROUP_CHECK" => "" } unless plan.cloudwatch_logs?
+
+            { "LOG_EXIT_CODE" => LOG_EXIT_CODE, "LOG_NOTE" => LOG_NOTE, "LOG_GROUP_CHECK" => LOG_GROUP_CHECK }
+          end
+
+          private
+
+          def awslogs_definition(plan, region)
+            options = %({"awslogs-region": "#{region}", "awslogs-group": "#{plan.log_group}", \
+"awslogs-create-group": "false", tag: $service})
+            %(def log($service): {driver: "awslogs", options: #{options}};)
+          end
+
+          def local_log_values
+            { "LOG_DEF" => "def log: #{JSON_FILE};", "LOG_SERVICE" => "log", "LOG_CADDY" => "log",
+              "LOG_TUNNEL" => "log" }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -45,7 +45,8 @@ module Hecks
                                            "RDS_STACK" => plan.rds_stack, "REGION" => region,
                                            "DIR" => "/opt/#{plan.infra_name}", "HEALTH_CHECKS" => health_checks(plan),
                                            "SMOKE_HEADER" => smoke_header(plan), "USAGE" => deploy_usage(plan),
-                                           "DB_SECRET_LINE" => database_secret_line(plan))
+                                           "DB_SECRET_LINE" => database_secret_line(plan),
+                                           **log_roll_values(plan))
           end
 
           # @param plan [Settings::Plan] the resolved settings
@@ -94,18 +95,25 @@ module Hecks
           end
 
           # @param plan [Settings::Plan] the resolved settings
+          # @param region [String] the validated region
           # @return [String] a Makefile whose targets create the two stacks and roll the box
-          def makefile(plan)
-            hint = plan.task_definition ? "[TASKDEF=family:revision]" : '[TAGS="web=20260101 worker=20260101"]'
-            base = template("Makefile.tmpl", { "STACK" => plan.infra_name, "DEPLOY_HINT" => hint,
-                                               "RDS_STACK" => plan.rds_stack, "BOX_STACK" => plan.box_stack,
-                                               "DEPLOY_RECIPE" => RollRecipe.deploy(plan) }
-                                               .merge(database_makefile_values(plan)))
-            plan.hosting ? "#{base}\ninclude hosting.mk\n" : base
+          def makefile(plan, region)
+            values = makefile_values(plan, region)
+            base = template("Makefile.tmpl", values)
+            includes = [("hosting.mk" if plan.hosting), ("edge.mk" if plan.cdn)].compact
+            includes.empty? ? base : "#{base}\n#{includes.map { |file| "include #{file}\n" }.join}"
           end
 
           private
 
+          def makefile_values(plan, region)
+            hint = plan.task_definition ? "[TASKDEF=family:revision]" : '[TAGS="web=20260101 worker=20260101"]'
+            { "STACK" => plan.infra_name, "DEPLOY_HINT" => hint, "RDS_STACK" => plan.rds_stack,
+              "BOX_STACK" => plan.box_stack, "DEPLOY_RECIPE" => RollRecipe.deploy(plan),
+              "AMI_PARAMETER" => ami_parameter(plan.instance_type) }
+              .merge(database_makefile_values(plan), edge_makefile_values(plan, region))
+          end
+
           def schema_list(migration)
             migration.schemas.map { |name| "`#{name}`" }.join(", ")
           end

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

@@ -0,0 +1,40 @@
+require_relative "patterns"
+
+module Hecks
+  module Projections
+    module Deploy
+      module Box
+        module Settings
+          # Reads the `cdn` setting: the CloudFront edge in front of the box. Extended onto
+          # `Settings`. The alias names themselves are checked by the Deploy bluebook's
+          # `BoxTarget.Declare` before this runs; this checks the shape and the guard.
+          module CdnReaders
+            include Patterns
+
+            # @param value [Hash{Symbol => Object}, nil] the world's `cdn` setting
+            # @param origin_header [String, nil] the declared origin header
+            # @return [Cdn, nil] the edge to generate, or nil when the world declares none
+            # @raise [ArgumentError] when the shape is wrong or there is no origin guard
+            def read_cdn(value, origin_header)
+              return nil if value.nil?
+
+              aliases = cdn_aliases(value)
+              raise ArgumentError, CDN_NEEDS_ORIGIN if origin_header.nil?
+
+              Settings::Cdn.new(aliases: aliases.uniq)
+            end
+
+            private
+
+            def cdn_aliases(value)
+              listed = value.is_a?(Hash) && value.keys == [:aliases] ? value[:aliases] : nil
+              raise ArgumentError, CDN_SHAPE unless listed.is_a?(Array) && !listed.empty?
+
+              listed.map { |name| check(:cdn_aliases, name, CDN_ALIAS) }
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,40 @@
+require_relative "patterns"
+
+module Hecks
+  module Projections
+    module Deploy
+      module Box
+        module Settings
+          # Reads the `logs` and `log_retention_days` settings: where the containers' logs go and
+          # how long CloudWatch keeps them. Extended onto `Settings`.
+          #
+          # Retention is one of CloudWatch's own values and never "never expire", so a box's log
+          # bill is bounded by a declaration.
+          module LogReaders
+            include Patterns
+
+            # @param settings [Hash{Symbol => Object}] the world's `AwsBox` settings
+            # @return [Hash{Symbol => Object}] the plan's `logs` and `log_retention_days`
+            # @raise [ArgumentError] when `logs` is not a known destination, or the retention is not
+            #   a value CloudWatch accepts
+            def read_logs(settings)
+              destination = settings.fetch(:logs, "cloudwatch").to_s
+              raise ArgumentError, LOGS_SHAPE unless LOG_DESTINATIONS.include?(destination)
+
+              days = settings.fetch(:log_retention_days, DEFAULT_LOG_RETENTION_DAYS)
+              raise ArgumentError, retention_refusal(days) unless LOG_RETENTION_DAYS.include?(days)
+
+              { logs: destination, log_retention_days: days }
+            end
+
+            private
+
+            def retention_refusal(days)
+              "log_retention_days: #{days.inspect} is not a CloudWatch retention; use one of #{LOG_RETENTION_DAYS.join(", ")}"
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -23,6 +23,13 @@ module Hecks
             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
+            LOG_DESTINATIONS = %w[cloudwatch local].freeze
+            DEFAULT_LOG_RETENTION_DAYS = 30
+            # The retention periods CloudWatch Logs accepts, in days, without "never expire".
+            LOG_RETENTION_DAYS = [1, 3, 5, 7, 14, 30, 60, 90, 120, 150, 180, 365, 400, 545, 731, 1096, 1827, 2192, 2557,
+                                  2922, 3288, 3653].freeze
+            LOGS_SHAPE = "logs: \"cloudwatch\" ships every container's log to CloudWatch Logs; " \
+                         "\"local\" keeps Docker's rotating json-file logs on the box".freeze
 
             # The settings that size an RDS instance: with `shared_database` they are the shared
             # instance's.
@@ -37,6 +44,10 @@ module Hecks
                            "(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
+            CDN_ALIAS = /\A[a-z0-9.-]{4,253}\z/
+            CDN_SHAPE = "cdn: a hash with `aliases`, the non-empty list of host names the CloudFront edge answers on".freeze
+            CDN_NEEDS_ORIGIN = "cdn: the box admits CloudFront's addresses on port 80, so it needs the origin guard " \
+                               "that refuses every other caller; declare origin_header and origin_secret".freeze
             ORIGIN_PAIR = "origin_header and origin_secret go together: the header a CDN sends, " \
                           "and the secret that holds its value".freeze
           end

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

@@ -45,18 +45,33 @@ module Hecks
             # @!attribute [r] write [Boolean] whether a production box may also write and delete
             Bucket = Struct.new(:name, :write, keyword_init: true)
 
+            # The CloudFront edge a world asks for with `cdn`.
+            #
+            # @!attribute [r] aliases [Array<String>] the host names the distribution answers on
+            Cdn = Struct.new(:aliases, 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, :shared_database, keyword_init: true
+              :task_definition, :migration, :s3_buckets, :hosting, :shared_database, :cdn,
+              :logs, :log_retention_days, keyword_init: true
             ) do
               # @return [String] the CloudFormation stack that holds the database: the shared
               #   instance's when the world names one, else this site's own
               def rds_stack = shared_database || "#{stack_prefix}-#{infra_name}-rds"
 
+              # @return [String] the CloudFormation stack that holds the CloudFront edge
+              def edge_stack = "#{stack_prefix}-#{infra_name}-edge"
+
+              # @return [String] the CloudWatch log group the box's containers write to
+              def log_group = "/#{box_stack}"
+
+              # @return [Boolean] whether the containers' logs ship to CloudWatch Logs
+              def cloudwatch_logs? = logs == "cloudwatch"
+
               # @return [Boolean] whether the database lives on an instance shared with other sites
               def shared? = !shared_database.nil?
 

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

@@ -4,6 +4,8 @@ require_relative "settings/types"
 require_relative "settings/checks"
 require_relative "settings/containers"
 require_relative "settings/origin"
+require_relative "settings/cdn"
+require_relative "settings/logs"
 
 module Hecks
   module Projections
@@ -21,6 +23,8 @@ module Hecks
           extend Checks
           extend ContainerReaders
           extend OriginReaders
+          extend CdnReaders
+          extend LogReaders
 
           module_function
 
@@ -50,7 +54,7 @@ module Hecks
               shared_database: read_shared_database(settings),
               s3_buckets: read_s3_access(settings.fetch(:s3_access, [])),
               hosting: HostingSettings.read(settings, task_definition)
-            }
+            }.merge(read_logs(settings))
           end
 
           # @param settings [Hash{Symbol => Object}] the world's `AwsBox` settings
@@ -62,7 +66,7 @@ module Hecks
             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 }
+              tunnel: tunnel, tunnel_service: tunnel_service, cdn: read_cdn(settings[:cdn], header) }
           end
 
           # @return [Hash{Symbol => Object}] the plan's names, sizes, routes and secret scopes

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

@@ -20,16 +20,19 @@ module Hecks
             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))
+                     "ECR_OUTPUTS" => ecr_outputs(plan), "S3_POLICY" => s3_policy(plan),
+                     "LOG_GROUP" => log_group_yaml(plan), "LOG_POLICY" => log_policy_yaml(plan))
           end
 
           # Graviton families end their generation digit with `g` (`t4g`, `m7gd`, `c6gn`).
           #
+          # Only a first create reads it, from `make stacks`: a live box keeps the image it runs,
+          # because a newer one would replace the instance.
+          #
           # @param instance_type [String] an EC2 instance type
           # @return [String] the SSM parameter of the matching Amazon Linux image
           def ami_parameter(instance_type)

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

@@ -1,21 +1,37 @@
 # @@STACK@@: @@WHAT@@.
 #   make stacks VPC=vpc-... PRIVATE_SUBNETS=subnet-a,subnet-b PUBLIC_SUBNET=subnet-c [REHEARSAL=true]
 #   make deploy @@DEPLOY_HINT@@
+# `make stacks` keeps a live box on the image it runs, so an update never replaces the instance.
+# To move to a newer image on purpose:  make stacks ... AMI_ID=ami-...
 RDS_STACK = @@RDS_STACK@@
 BOX_STACK = @@BOX_STACK@@
 @@REHEARSAL_NOTE@@
 REHEARSAL ?= false
+AMI_ID ?=
 
 HECKS ?= hecks
 
 @@PHONY@@
 stacks:
+@@CDN_CHECK@@
 @@RDS_DEPLOY@@
+	@AMI="$(AMI_ID)"; SRC="given as AMI_ID"; \
+	if [ -z "$$AMI" ]; then \
+		BOX=$$(aws cloudformation describe-stack-resource --stack-name $(BOX_STACK) --logical-resource-id Box --query StackResourceDetail.PhysicalResourceId --output text 2>/dev/null); \
+		case "$$BOX" in \
+			i-*) AMI=$$(aws ec2 describe-instances --instance-ids "$$BOX" --query "Reservations[0].Instances[0].ImageId" --output text); SRC="pinned: the image $$BOX runs" ;; \
+			*) AMI=$$(aws ssm get-parameter --name @@AMI_PARAMETER@@ --query Parameter.Value --output text); SRC="new: no $(BOX_STACK) stack yet, so the latest image" ;; \
+		esac; \
+	fi; \
+	case "$$AMI" in ami-*) ;; *) echo "no ami- image found for $(BOX_STACK): pass one with AMI_ID=ami-..." >&2; exit 1 ;; esac; \
+	echo "==> AmiId $$AMI ($$SRC)"; \
 	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) \
 @@DB_SECRET_PARAM@@
+		AmiId=$$AMI \
 		AlertTopicArn=$$(aws cloudformation describe-stacks --stack-name $(RDS_STACK) --query "Stacks[0].Outputs[?OutputKey=='AlertTopicArn'].OutputValue" --output text) \
+@@CDN_PARAM@@
 		Rehearsal=$(REHEARSAL)
 
 @@PROVISION@@

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

@@ -20,9 +20,12 @@ Parameters:
     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.
+    Type: AWS::EC2::Image::Id
+    Description: >-
+      The image the box runs, always given and never resolved here. Resolving the public image
+      key again on a live box finds the newest image, and a changed ImageId replaces the instance
+      and its Elastic IP association. make stacks passes the running box's own image, and takes a
+      newer one only when AMI_ID is given.
   RootVolumeGb:
     Type: Number
     Default: @@VOLUME_GB@@
@@ -82,7 +85,7 @@ Resources:
       SourceSecurityGroupId: !Ref BoxSecurityGroup
       Description: App box
 
-  BoxRole:
+@@LOG_GROUP@@  BoxRole:
     Type: AWS::IAM::Role
     Properties:
       AssumeRolePolicyDocument:
@@ -106,6 +109,7 @@ Resources:
 @@SECRET_RESOURCES@@
 @@WRITABLE_SECRETS@@
 @@S3_POLICY@@
+@@LOG_POLICY@@
 
   BoxProfile:
     Type: AWS::IAM::InstanceProfile

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

@@ -10,6 +10,7 @@
 #   42  the roll succeeded but the box is not healthy after it
 #   43  no restore anchor: the database's backups cannot be read, or are kept fewer days than
 #       MIN_BACKUP_RETENTION_DAYS (default 3)
+@@LOG_EXIT_CODE@@
 #
 # Before anything changes, the roll names the point the database can be restored to: the instance, the
 # moment this roll starts, and how long its continuous backups are kept. A roll that mints a new era is
@@ -23,6 +24,7 @@
 # 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).
 #
+@@LOG_NOTE@@
 @@USAGE@@
 set -euo pipefail
 HERE=$(cd "$(dirname "$0")" && pwd)
@@ -37,6 +39,7 @@ DB_HOST=$(out "$RDS_STACK" DbEndpoint)
 @@DB_SECRET_LINE@@
 [ -n "$BOX" ] && [ "$BOX" != None ] || { echo "no instance in stack $BOX_STACK" >&2; exit 40; }
 ACCOUNT=$(aws sts get-caller-identity --query Account --output text)
+@@LOG_GROUP_CHECK@@
 
 if [ "${SKIP_RESTORE_ANCHOR:-}" = 1 ]; then
   echo "==> skipping the restore anchor (SKIP_RESTORE_ANCHOR=1)"

data/lib/hecks/projections/deploy/box/templates/edge.mk.tmpl

@@ -0,0 +1,17 @@
+# GENERATED by hecks deploy project -- re-run it to refresh this file rather than hand-editing.
+# Included by the Makefile beside it; the aliases come from the domain's deployed_to("AwsBox")
+# block (cdn).
+
+EDGE_STACK = @@EDGE_STACK@@
+
+.PHONY: edge
+
+# Creates or updates the CloudFront edge stack in front of the box (run `make stacks` first: the
+# box's AppOriginDomain output is the distribution's origin). The certificate is never created
+# here: issue it in ACM in us-east-1, validate its DNS records, then pass its ARN.
+#   make edge CERTIFICATE_ARN=arn:aws:acm:us-east-1:<account>:certificate/<id>
+edge:
+	@test -n "$(CERTIFICATE_ARN)" || { echo "usage: make edge CERTIFICATE_ARN=arn:aws:acm:us-east-1:..." >&2; exit 1; }
+	aws cloudformation deploy --region @@REGION@@ --template-file edge.yaml --stack-name $(EDGE_STACK) \
+		--parameter-overrides CertificateArn=$(CERTIFICATE_ARN) \
+		AppOriginDomain=$$(aws cloudformation describe-stacks --region @@REGION@@ --stack-name $(BOX_STACK) --query "Stacks[0].Outputs[?OutputKey=='AppOriginDomain'].OutputValue" --output text)

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

@@ -0,0 +1,65 @@
+AWSTemplateFormatVersion: "2010-09-09"
+Description: >
+  The CloudFront edge of @@STACK@@: one distribution in front of the app box. Its only origin is the
+  box's public DNS name over plain http on port 80, and every request to it carries the origin secret
+  header the box's proxy checks. Nothing is cached: the origin decides what a response means.
+
+Parameters:
+  AppOriginDomain:
+    Type: String
+    AllowedPattern: ".+"
+    ConstraintDescription: the box stack's AppOriginDomain output
+    Description: DNS name of the app box, the distribution's only origin.
+  CertificateArn:
+    Type: String
+    AllowedPattern: "arn:aws:acm:us-east-1:.+"
+    ConstraintDescription: an ACM certificate in us-east-1 that covers every alias
+    Description: >
+      An issued ACM certificate in us-east-1 that covers every name in DomainNames. It is never created
+      here: DNS validation is a step an operator performs.
+  DomainNames:
+    Type: CommaDelimitedList
+    Default: "@@ALIASES@@"
+    Description: The host names the distribution answers on.
+
+Resources:
+  Distribution:
+    Type: AWS::CloudFront::Distribution
+    DeletionPolicy: Retain
+    UpdateReplacePolicy: Retain
+    Properties:
+      DistributionConfig:
+        Enabled: true
+        HttpVersion: http2
+        IPV6Enabled: true
+        Aliases: !Ref DomainNames
+        ViewerCertificate:
+          AcmCertificateArn: !Ref CertificateArn
+          SslSupportMethod: sni-only
+          MinimumProtocolVersion: TLSv1.2_2021
+        Origins:
+          - Id: BoxOrigin
+            DomainName: !Ref AppOriginDomain
+            OriginCustomHeaders:
+              # Resolved by CloudFormation from Secrets Manager when the stack deploys, so the value
+              # never appears on a command line or in this file.
+              - HeaderName: @@ORIGIN_HEADER@@
+                HeaderValue: "{{resolve:secretsmanager:@@ORIGIN_SECRET@@:SecretString}}"
+            CustomOriginConfig:
+              OriginProtocolPolicy: http-only
+              OriginSSLProtocols: [TLSv1.2]
+        DefaultCacheBehavior:
+          TargetOriginId: BoxOrigin
+          ViewerProtocolPolicy: redirect-to-https
+          AllowedMethods: [GET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE]
+          CachedMethods: [GET, HEAD]
+          Compress: true
+          CachePolicyId: 4135ea2d-6df8-44a3-9df3-4b5a84be39ad # Managed-CachingDisabled
+          OriginRequestPolicyId: 216adef6-5c7f-47e4-b989-5492eafa07d3 # Managed-AllViewer
+
+Outputs:
+  DistributionId:
+    Value: !Ref Distribution
+  DistributionDomainName:
+    Description: Point each alias's DNS record (CNAME or alias) at this name.
+    Value: !GetAtt Distribution.DomainName

data/lib/hecks/projections/deploy/box/templates/log-group.yaml.tmpl

@@ -0,0 +1,12 @@
+  # Every container's log, one stream per service. The group is made here and not by Docker
+  # (awslogs-create-group is "false"), so the role below needs no right to create groups, and the
+  # retention is a declaration. A production group outlives the stack: the evidence a container
+  # wrote must not go with a deleted stack.
+  BoxLogGroup:
+    Type: AWS::Logs::LogGroup
+    DeletionPolicy: !If [IsProduction, Retain, Delete]
+    UpdateReplacePolicy: !If [IsProduction, Retain, Delete]
+    Properties:
+      LogGroupName: @@LOG_GROUP@@
+      RetentionInDays: @@RETENTION_DAYS@@
+

data/lib/hecks/projections/deploy/box/templates/log-policy.yaml.tmpl

@@ -0,0 +1,7 @@
+        - PolicyName: write-logs
+          PolicyDocument:
+            Version: "2012-10-17"
+            Statement:
+              - Effect: Allow
+                Action: [logs:CreateLogStream, logs:PutLogEvents, logs:DescribeLogStreams]
+                Resource: !GetAtt BoxLogGroup.Arn

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

@@ -13,6 +13,7 @@
 # When the world names origin_env, the named origin secret is compared with those variables in the
 # task definition and the render refuses on any difference (Caddy checks the CDN's header against
 # the secret; the containers check it against their own copy). Values are never printed.
+@@COMPOSE_LOG_NOTE@@
 set -euo pipefail
 HERE=$(cd "$(dirname "$0")" && pwd)
 DB_HOST=${1:?rds endpoint}
@@ -36,7 +37,7 @@ if [ -n "$ORIGIN_ENV" ]; then
 fi
 
 jq --argjson def "$DEF" --arg host "$DB_HOST" --arg secret "$DB_SECRET" '
-  def log: {driver: "json-file", options: {"max-size": "10m", "max-file": "3"}};
+  @@LOG_DEF@@
   def env(c): ((c.environment // []) | map({(.name): .value}) | add // {})
     | (if has("DB_HOST") then .DB_HOST = $host | .DB_SECRET_ARN = $secret else . end);
   . as $in
@@ -44,16 +45,16 @@ jq --argjson def "$DEF" --arg host "$DB_HOST" --arg secret "$DB_SECRET" '
       ($in.services | with_entries(.value |= (. as $s
         | ($def | map(select(.name == $s.name)) | first) as $c
         | if $c == null then error("task definition has no container named " + $s.name) else
-            {image: $c.image, network_mode: "host", restart: "unless-stopped", logging: log,
+            {image: $c.image, network_mode: "host", restart: "unless-stopped", logging: @@LOG_SERVICE@@,
              environment: ({PORT: ($s.port | tostring)} + env($c))}
             + (if (($c.secrets // []) | length) > 0 then {env_file: [($s.name + ".secrets.env")]} else {} end)
           end)))
       + {caddy: ({image: "@@PROXY_IMAGE@@", network_mode: "host", restart: "unless-stopped",
-                  volumes: ["./Caddyfile:/etc/caddy/Caddyfile:ro", "./caddy-extra:/etc/caddy/extra:ro"], logging: log}
+                  volumes: ["./Caddyfile:/etc/caddy/Caddyfile:ro", "./caddy-extra:/etc/caddy/extra:ro"], logging: @@LOG_CADDY@@}
                  + (if $in.origin then {env_file: ["caddy.secrets.env"]} else {} end))}
       + (if $in.tunnel then {cloudflared: {image: $in.tunnel.image, network_mode: "host", restart: "unless-stopped",
                   command: ["tunnel", "--no-autoupdate", "--url", $in.tunnel.url, "run"],
-                  env_file: ["cloudflared.secrets.env"], logging: log}} else {} end))}' \
+                  env_file: ["cloudflared.secrets.env"], logging: @@LOG_TUNNEL@@}} else {} end))}' \
   "$HERE/services.json" > compose.json
 
 jq --argjson def "$DEF" '. as $in

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

@@ -6,6 +6,7 @@
 # Tags default to "latest". Every container gets DB_HOST, DB_NAME, DB_SECRET_ARN and PORT, and runs on the
 # box's own network, so the proxy reaches each one on 127.0.0.1:<port>. Secrets named in services.json
 # are written to secrets.json for fetch-secrets.sh to resolve on the box.
+@@COMPOSE_LOG_NOTE@@
 set -euo pipefail
 HERE=$(cd "$(dirname "$0")" && pwd)
 DB_HOST=${1:?rds endpoint}
@@ -18,20 +19,20 @@ ECR="$ACCOUNT.dkr.ecr.$REGION.amazonaws.com"
 TAGS=$(printf '%s\n' "$@" | jq -R 'select(length > 0) | split("=") | {(.[0]): .[1]}' | jq -s 'add // {}')
 
 jq --arg ecr "$ECR" --argjson tags "$TAGS" --arg host "$DB_HOST" --arg secret "$DB_SECRET" --arg db "@@DB_NAME@@" '
-  def log: {driver: "json-file", options: {"max-size": "10m", "max-file": "3"}};
+  @@LOG_DEF@@
   . as $in
   | {services: (
       ($in.services | with_entries(.value |= (
         {image: ($ecr + "/" + .repository + ":" + ($tags[.name] // "latest")),
-         network_mode: "host", restart: "unless-stopped", logging: log,
+         network_mode: "host", restart: "unless-stopped", logging: @@LOG_SERVICE@@,
          environment: ({PORT: (.port | tostring), DB_HOST: $host, DB_NAME: $db, DB_SECRET_ARN: $secret} + .env)}
         + (if (.secrets | length) > 0 then {env_file: [(.name + ".secrets.env")]} else {} end))))
       + {caddy: ({image: "@@PROXY_IMAGE@@", network_mode: "host", restart: "unless-stopped",
-                  volumes: ["./Caddyfile:/etc/caddy/Caddyfile:ro", "./caddy-extra:/etc/caddy/extra:ro"], logging: log}
+                  volumes: ["./Caddyfile:/etc/caddy/Caddyfile:ro", "./caddy-extra:/etc/caddy/extra:ro"], logging: @@LOG_CADDY@@}
                  + (if $in.origin then {env_file: ["caddy.secrets.env"]} else {} end))}
       + (if $in.tunnel then {cloudflared: {image: $in.tunnel.image, network_mode: "host", restart: "unless-stopped",
                   command: ["tunnel", "--no-autoupdate", "--url", $in.tunnel.url, "run"],
-                  env_file: ["cloudflared.secrets.env"], logging: log}} else {} end))}' \
+                  env_file: ["cloudflared.secrets.env"], logging: @@LOG_TUNNEL@@}} else {} end))}' \
   "$HERE/services.json" > compose.json
 
 jq '. as $in