@ossy/deployment-tools 3.1.0 → 3.4.0

package/CHANGELOG.md

@@ -3,6 +3,13 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [3.4.0](https://github.com/ossy-se/ossy/compare/v3.3.0...v3.4.0) (2026-08-14)
+
+### Features
+
+* **deployment-tools:** add ECS container /health probes ([#589](https://github.com/ossy-se/ossy/issues/589)) ([0761f19](https://github.com/ossy-se/ossy/commit/0761f19a695f98470fccdcd9fc90ae0af288d7f3)), closes [#553](https://github.com/ossy-se/ossy/issues/553) [#553](https://github.com/ossy-se/ossy/issues/553)
+
+
 # [3.1.0](https://github.com/ossy-se/ossy/compare/v3.0.9...v3.1.0) (2026-08-12)
 
 ### Features

package/README.md

@@ -16,7 +16,7 @@ Internet → CloudFront (ACM TLS, us-east-1) → WAF → ALB (:80)
 
 - Website images include the API — **no** separate `ossy-api` service.
 - Task definitions inject env from Secrets Manager (`{platform}/{serviceKey}`) and pull images from GHCR using `{platform}/ghcr-pull`.
-- Health checks use `GET /health` on each target group.
+- Health checks use `GET /health` on each ALB target group **and** each ECS container (Node `fetch` probe; no curl in `node:*-slim`).
 - App CloudFront is **separate** from the `/media` CloudFront in `storage-static`.
 - Viewer `Host` is forwarded to the ALB (`OriginRequestPolicy.ALL_VIEWER`) so host rules match.
 - ACM terminates TLS at CloudFront; Caddy is not part of this path.
@@ -26,14 +26,16 @@ Customer nameserver / custom-domain handoff at a registrar is **out of scope** (
 
 ## Health checks (ALB / ECS)
 
-Every deployable Ossy HTTP image exposes an unauthenticated liveness probe at **`GET /health`** (also accepts `HEAD`). It returns `200` when the Node process can accept traffic.
+Every deployable Ossy HTTP image exposes an unauthenticated liveness probe at **`GET /health`** (also accepts `HEAD`). It returns `200` when the Node process can accept traffic. The JSON `service` field prefers **`OSSY_SERVICE_NAME`** (set on the task definition to the service key).
 
 | Image | How `/health` is provided |
 |---|---|
 | `ghcr.io/ossy-se/platform` (runtime) | Built into `@ossy/platform` `startRuntime` — does not load a CMS site |
 | Website / app images (`website-ossy`, other `services[]`) | Built into `@ossy/platform` `startServer` (and/or a local `health.api.js` until the platform package is bumped) |
 
-Use path `/health` for ALB target-group and ECS container health checks. Do not point probes at `/`, `/status`, or authenticated routes.
+**ALB target groups** probe `GET /health`. **ECS container health checks** run an exec-form Node one-liner (`ecsContainerHealthCheckCommand`) that `fetch`es the same path on `PORT` and aborts after `HEALTHCHECK_FETCH_TIMEOUT_MS` (4s). Do not point probes at `/`, `/status`, or authenticated routes.
+
+Task definitions also set plain env `PORT`, `OSSY_SERVICE_NAME`, `NODE_ENV`, and media bucket vars via `containerEnvironment`. Those keys are **filtered out** of Secrets Manager injection (`secretEnvKeysForEcsContainer`) so ECS cannot reject duplicate environment/secret keys.
 
 ## Configuration — `platforms.json`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ossy/deployment-tools",
-  "version": "3.1.0",
+  "version": "3.4.0",
   "description": "Collection of scripts and tools to aid deployment of containers and static files to Amazon Web Services through GitHub Actions",
   "source": "./src/index.js",
   "main": "./src/index.js",
@@ -24,5 +24,5 @@
   "devDependencies": {
     "jest": "^30.4.2"
   },
-  "gitHead": "9b146fb6fd9769f800863806c5bd16016508b218"
+  "gitHead": "d36b69444268d172bc3e8e1dc77e67afc63f8650"
 }

package/src/ecs/platform-ecs-services.js

@@ -13,6 +13,25 @@ const {
 
 const RUNTIME_IMAGE = 'ghcr.io/ossy-se/platform:latest'
 const CONTAINER_PORT = 3000
+/** Shared with `@ossy/platform` `HEALTH_PATH` and ALB target-group checks. */
+const HEALTH_PATH = '/health'
+/**
+ * Abort hung Node `fetch` probes under the usual 5s ECS/Docker check timeout.
+ * Keep in sync with website-ossy `docker-healthcheck.js` when that lands.
+ */
+const HEALTHCHECK_FETCH_TIMEOUT_MS = 4000
+
+/**
+ * Plain task-definition `environment` keys set by PlatformEcsStack.
+ * Must not also be injected from Secrets Manager (ECS rejects duplicate keys).
+ */
+const CONTAINER_ENVIRONMENT_KEYS = Object.freeze([
+  'NODE_ENV',
+  'PORT',
+  'OSSY_SERVICE_NAME',
+  'MEDIA_REPOSITORY',
+  'MEDIA_CDN_DOMAIN_NAME',
+])
 
 /**
  * @typedef {Object} PlatformEcsService
@@ -25,6 +44,79 @@ const CONTAINER_PORT = 3000
  * @property {number} containerPort - container listen port
  */
 
+/**
+ * Env keys from `platforms.json` that may be injected as ECS secrets.
+ * Drops keys already set as plain container environment.
+ *
+ * @param {string[]} envKeys
+ * @returns {string[]}
+ */
+function secretEnvKeysForEcsContainer(envKeys = []) {
+  if (!Array.isArray(envKeys)) {
+    throw new Error('[platform-ecs-services] envKeys must be an array')
+  }
+  const reserved = new Set(CONTAINER_ENVIRONMENT_KEYS)
+  return envKeys.filter((key) => typeof key === 'string' && key && !reserved.has(key))
+}
+
+/**
+ * Plain task-definition `environment` for an ECS HTTP container.
+ *
+ * Keys must stay aligned with `CONTAINER_ENVIRONMENT_KEYS` so Secrets Manager
+ * injection cannot collide with these values.
+ *
+ * @param {{
+ *   serviceKey: string,
+ *   containerPort?: number,
+ *   mediaRepository: string,
+ *   mediaCdnDomainName: string,
+ * }} options
+ * @returns {Record<string, string>}
+ */
+function containerEnvironment({
+  serviceKey,
+  containerPort = CONTAINER_PORT,
+  mediaRepository,
+  mediaCdnDomainName,
+}) {
+  if (!serviceKey) {
+    throw new Error('[platform-ecs-services] serviceKey is required')
+  }
+  if (!mediaRepository || !mediaCdnDomainName) {
+    throw new Error('[platform-ecs-services] mediaRepository and mediaCdnDomainName are required')
+  }
+  return {
+    NODE_ENV: 'production',
+    PORT: String(containerPort),
+    OSSY_SERVICE_NAME: serviceKey,
+    MEDIA_REPOSITORY: mediaRepository,
+    MEDIA_CDN_DOMAIN_NAME: mediaCdnDomainName,
+  }
+}
+
+/**
+ * ECS container health-check command for Ossy HTTP images.
+ *
+ * Uses Node `fetch` against `HEALTH_PATH` (honors runtime `PORT`) so probes
+ * work on `node:*-slim` without curl/wget and without requiring a WORKDIR
+ * `docker-healthcheck.js` in every image. Abort after
+ * `HEALTHCHECK_FETCH_TIMEOUT_MS` so hung sockets fail under the 5s timeout.
+ *
+ * @param {{ containerPort?: number }} [options]
+ * @returns {string[]} Docker/ECS exec-form health check command
+ */
+function ecsContainerHealthCheckCommand({ containerPort = CONTAINER_PORT } = {}) {
+  const portFallback = Number(containerPort) > 0 ? Number(containerPort) : CONTAINER_PORT
+  // Single expression — ECS passes each CMD arg without a shell.
+  const probe = [
+    `const port=Number.parseInt(String(process.env.PORT||''),10);`,
+    `const p=Number.isFinite(port)&&port>0?port:${portFallback};`,
+    `fetch('http://127.0.0.1:'+p+'${HEALTH_PATH}',{signal:AbortSignal.timeout(${HEALTHCHECK_FETCH_TIMEOUT_MS})})`,
+    `.then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))`,
+  ].join('')
+  return ['CMD', 'node', '-e', probe]
+}
+
 /**
  * Host headers for an HTTP `services[]` entry.
  * Uses optional `hosts` when set; otherwise `[domain]`.
@@ -105,6 +197,12 @@ function listPlatformEcsServices(config) {
 module.exports = {
   RUNTIME_IMAGE,
   CONTAINER_PORT,
+  HEALTH_PATH,
+  HEALTHCHECK_FETCH_TIMEOUT_MS,
+  CONTAINER_ENVIRONMENT_KEYS,
+  secretEnvKeysForEcsContainer,
+  containerEnvironment,
+  ecsContainerHealthCheckCommand,
   hostsFromServiceEntry,
   listPlatformEcsServices,
   runtimeHosts,

package/src/ecs/platform-ecs-services.spec.js

@@ -1,10 +1,96 @@
 const { describe, expect, it } = require('@jest/globals')
+const fs = require('node:fs')
+const path = require('node:path')
 const {
+  CONTAINER_ENVIRONMENT_KEYS,
+  CONTAINER_PORT,
+  HEALTH_PATH,
+  HEALTHCHECK_FETCH_TIMEOUT_MS,
   RUNTIME_IMAGE,
+  containerEnvironment,
+  ecsContainerHealthCheckCommand,
   hostsFromServiceEntry,
   listPlatformEcsServices,
+  secretEnvKeysForEcsContainer,
 } = require('./platform-ecs-services')
 
+describe('shared health constants', () => {
+  it('stay aligned with @ossy/platform health.js (ALB + ECS probes)', () => {
+    const healthSrc = fs.readFileSync(
+      path.join(__dirname, '../../../platform/src/health.js'),
+      'utf8'
+    )
+    expect(healthSrc).toContain(`export const HEALTH_PATH = '${HEALTH_PATH}'`)
+    expect(HEALTH_PATH).toBe('/health')
+    expect(HEALTHCHECK_FETCH_TIMEOUT_MS).toBe(4000)
+    expect(CONTAINER_PORT).toBe(3000)
+  })
+})
+
+describe('ecsContainerHealthCheckCommand', () => {
+  it('probes HEALTH_PATH with Node fetch and abort timeout', () => {
+    const command = ecsContainerHealthCheckCommand()
+    expect(command[0]).toBe('CMD')
+    expect(command[1]).toBe('node')
+    expect(command[2]).toBe('-e')
+    expect(command[3]).toContain(`'${HEALTH_PATH}'`)
+    expect(command[3]).toContain(`AbortSignal.timeout(${HEALTHCHECK_FETCH_TIMEOUT_MS})`)
+    expect(command[3]).toContain(String(CONTAINER_PORT))
+    expect(command[3]).toContain('process.env.PORT')
+  })
+
+  it('honors an explicit containerPort fallback', () => {
+    const command = ecsContainerHealthCheckCommand({ containerPort: 3002 })
+    expect(command[3]).toContain('3002')
+  })
+})
+
+describe('containerEnvironment', () => {
+  it('uses exactly CONTAINER_ENVIRONMENT_KEYS (reserved for secret filtering)', () => {
+    const env = containerEnvironment({
+      serviceKey: 'website-ossy',
+      containerPort: 3000,
+      mediaRepository: 'media-bucket',
+      mediaCdnDomainName: 'https://cdn.example',
+    })
+    expect(Object.keys(env).sort()).toEqual([...CONTAINER_ENVIRONMENT_KEYS].sort())
+    expect(env).toEqual({
+      NODE_ENV: 'production',
+      PORT: '3000',
+      OSSY_SERVICE_NAME: 'website-ossy',
+      MEDIA_REPOSITORY: 'media-bucket',
+      MEDIA_CDN_DOMAIN_NAME: 'https://cdn.example',
+    })
+  })
+
+  it('requires serviceKey and media fields', () => {
+    expect(() => containerEnvironment({
+      mediaRepository: 'b',
+      mediaCdnDomainName: 'https://cdn.example',
+    })).toThrow(/serviceKey is required/)
+    expect(() => containerEnvironment({ serviceKey: 'runtime' })).toThrow(
+      /mediaRepository and mediaCdnDomainName are required/
+    )
+  })
+})
+
+describe('secretEnvKeysForEcsContainer', () => {
+  it('drops reserved container environment keys', () => {
+    expect(secretEnvKeysForEcsContainer([
+      'PORT',
+      'OSSY_SERVICE_NAME',
+      'TOKEN_SECRET',
+      'NODE_ENV',
+      'MEDIA_REPOSITORY',
+      'DB_URL',
+    ])).toEqual(['TOKEN_SECRET', 'DB_URL'])
+  })
+
+  it('requires an array', () => {
+    expect(() => secretEnvKeysForEcsContainer(null)).toThrow(/envKeys must be an array/)
+  })
+})
+
 describe('hostsFromServiceEntry', () => {
   it('uses hosts when provided', () => {
     expect(hostsFromServiceEntry({

package/src/index.js

@@ -12,6 +12,12 @@ const {
   hostsFromServiceEntry,
   RUNTIME_IMAGE,
   CONTAINER_PORT,
+  HEALTH_PATH,
+  HEALTHCHECK_FETCH_TIMEOUT_MS,
+  CONTAINER_ENVIRONMENT_KEYS,
+  secretEnvKeysForEcsContainer,
+  containerEnvironment,
+  ecsContainerHealthCheckCommand,
 } = require('./ecs/platform-ecs-services')
 const {
   rootDomainOf,
@@ -31,6 +37,12 @@ module.exports = {
   hostsFromServiceEntry,
   RUNTIME_IMAGE,
   CONTAINER_PORT,
+  HEALTH_PATH,
+  HEALTHCHECK_FETCH_TIMEOUT_MS,
+  CONTAINER_ENVIRONMENT_KEYS,
+  secretEnvKeysForEcsContainer,
+  containerEnvironment,
+  ecsContainerHealthCheckCommand,
   rootDomainOf,
   listEdgeAliases,
   planEdgeDomains,

package/src/infrastructure/platform-ecs-stack.js

@@ -31,7 +31,14 @@ const {
   ServicePrincipal,
 } = require('aws-cdk-lib/aws-iam')
 const { LogGroup, RetentionDays } = require('aws-cdk-lib/aws-logs')
-const { listPlatformEcsServices } = require('../ecs/platform-ecs-services')
+const {
+  CONTAINER_PORT,
+  HEALTH_PATH,
+  containerEnvironment,
+  ecsContainerHealthCheckCommand,
+  listPlatformEcsServices,
+  secretEnvKeysForEcsContainer,
+} = require('../ecs/platform-ecs-services')
 
 /**
  * @typedef {Object} PlatformEcsStackProps
@@ -103,7 +110,7 @@ class PlatformEcsStack extends Stack {
     })
     serviceSecurityGroup.addIngressRule(
       albSecurityGroup,
-      Port.tcp(3000),
+      Port.tcp(CONTAINER_PORT),
       'ALB to Fargate containers'
     )
 
@@ -169,8 +176,12 @@ class PlatformEcsStack extends Stack {
         executionRole,
       })
 
+      // Secrets must not redefine plain `environment` keys (PORT, OSSY_SERVICE_NAME, …).
       const containerSecrets = Object.fromEntries(
-        envKeys.map(key => [key, EcsSecret.fromSecretsManager(secret, key)])
+        secretEnvKeysForEcsContainer(envKeys).map(key => [
+          key,
+          EcsSecret.fromSecretsManager(secret, key),
+        ])
       )
 
       const container = taskDefinition.addContainer(`Container${idSuffix}`, {
@@ -182,13 +193,24 @@ class PlatformEcsStack extends Stack {
           streamPrefix: service.key,
           logGroup,
         }),
-        environment: {
-          NODE_ENV: 'production',
-          PORT: String(service.containerPort),
-          MEDIA_REPOSITORY: props.bucket.bucketName,
-          MEDIA_CDN_DOMAIN_NAME: `https://${props.cdnDomainName}`,
-        },
+        // Labels `/health` via OSSY_SERVICE_NAME; keys stay in CONTAINER_ENVIRONMENT_KEYS.
+        environment: containerEnvironment({
+          serviceKey: service.key,
+          containerPort: service.containerPort,
+          mediaRepository: props.bucket.bucketName,
+          mediaCdnDomainName: `https://${props.cdnDomainName}`,
+        }),
         secrets: containerSecrets,
+        // Node fetch → GET /health (no curl in node:*-slim; no image-local script required).
+        healthCheck: {
+          command: ecsContainerHealthCheckCommand({
+            containerPort: service.containerPort,
+          }),
+          interval: Duration.seconds(30),
+          timeout: Duration.seconds(5),
+          retries: 3,
+          startPeriod: Duration.seconds(60),
+        },
       })
 
       container.addPortMappings({
@@ -205,6 +227,7 @@ class PlatformEcsStack extends Stack {
         securityGroups: [serviceSecurityGroup],
         vpcSubnets: { subnetType: SubnetType.PRIVATE_WITH_EGRESS },
         circuitBreaker: { rollback: true },
+        healthCheckGracePeriod: Duration.seconds(60),
       })
 
       const targetGroup = new ApplicationTargetGroup(this, `TargetGroup${idSuffix}`, {
@@ -214,7 +237,7 @@ class PlatformEcsStack extends Stack {
         targetType: TargetType.IP,
         targetGroupName: truncateAwsName(`${platformName}-${service.key}`, 32),
         healthCheck: {
-          path: '/health',
+          path: HEALTH_PATH,
           healthyHttpCodes: '200',
           interval: Duration.seconds(30),
           timeout: Duration.seconds(5),