@ossy/deployment-tools 1.17.11 → 1.18.0

package/CHANGELOG.md

@@ -3,6 +3,25 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# 1.18.0 (2026-05-25)
+
+
+### Features
+
+* **deployment-tools:** Add OSSY_API_URL environment variable for container deployment ([d09ae18](https://github.com/ossy-se/ossy/commit/d09ae18b5255e4c49fd5387c76d1af6a24b0ba22))
+
+
+
+
+
+## 1.17.12 (2026-05-25)
+
+**Note:** Version bump only for package @ossy/deployment-tools
+
+
+
+
+
 ## 1.17.11 (2026-05-25)
 
 **Note:** Version bump only for package @ossy/deployment-tools

package/README.md

@@ -2,75 +2,79 @@
 
 Infrastructure and CDK tooling for the Ossy platform EC2 host.
 
-The host runs three services: **Caddy** (TLS + reverse proxy), **ossy-api** (the platform API), and **ossy-runtime** (the multi-tenant SSR server). Apps are deployed by running `ossy app publish`
+The host runs Caddy as a reverse proxy plus several Docker containers managed by systemd. Apps are deployed by running `ossy app publish`.
 
 ## Architecture
 
 ```
 Internet → Caddy (:443)
-             ├── api.ossy.se → ossy-api (:3001)
-             └── *.* (on-demand TLS) → ossy-runtime (:3000)
-                                            └── loads build from CMS on first request
+             ├── api.ossy.se          → ossy-api (:3001)
+             ├── ossy.se              → ossy-website-ossy (:3002)  ← temporary
+             ├── www.plexus-sanitas.com → ossy-website-plexus-sanitas (:3003)  ← temporary
+             └── *.* (on-demand TLS)  → ossy-platform (:3000)
+                                           └── loads build from CMS on first request
 ```
 
-Caddy uses **on-demand TLS**: before issuing a certificate for any domain, it calls `GET http://localhost:3001/api/v0/apps/ask?domain=<domain>`. If the domain is registered (i.e. `ossy app publish` has been run for it), Caddy issues the cert and proxies to the runtime.
+Caddy uses **on-demand TLS**: before issuing a certificate for any domain, it calls `GET http://localhost:3001/api/v0/apps/ask?domain=<domain>`. If the domain is registered (i.e. `ossy app publish` has been run for it), Caddy issues the cert and proxies to the platform runtime.
 
 ## Services
 
 All services run as Docker containers managed by systemd. Service files are written to the EC2 host by CDK user data at instance creation.
 
-| Service | Unit file | Port | Auto-start |
-|---|---|---|---|
-| Caddy | `caddy-route53.service` | 80, 443 | Yes |
-| Ossy API | `ossy-api.service` | 3001 | Yes |
-| Ossy Runtime | `ossy-runtime.service` | 3000 | Yes |
+| Service | Unit file | Port | Auto-start | Image |
+|---|---|---|---|---|
+| Caddy | `caddy-route53.service` | 80, 443 | Yes | — |
+| Ossy API | `ossy-api.service` | 3001 | Yes | `ghcr.io/ossy-se/api:latest` |
+| Ossy Platform | `ossy-runtime.service` | 3000 | Yes | `ghcr.io/ossy-se/platform:latest` |
+| website-ossy | `ossy-website-ossy.service` | 3002 | Yes | `ghcr.io/ossy-se/website-ossy:latest` |
+| website-plexus-sanitas | `ossy-website-plexus-sanitas.service` | 3003 | Yes | `ghcr.io/ossy-se/website-plexus-sanitas:latest` |
 
-All three services start automatically on first boot:
-
-- **Runtime** — image built from the published `@ossy/platform` npm package (no repo needed)
-- **API** — image pulled from `ghcr.io/ossy-se/api:latest` (pushed by CI on every merge to main). The `ExecStartPre` in the service unit pulls the latest image before each start, so redeploying is just `systemctl restart ossy-api`
+> **TODO (website-ossy, website-plexus-sanitas):** These are temporary services. Once `ossy app publish` is validated for each site, remove their service files and Caddy blocks so traffic flows through the platform runtime instead.
 
 > **TODO:** Pin `@ossy/platform` to a specific version at CDK deploy time (thread through `PlatformConfig`) rather than always pulling `@latest`.
 
+## Configuration — `platforms.json`
+
+`packages/infrastructure/platforms.json` is the single source of truth for a platform. It contains:
+
+- **AWS config** — account ID, key pair, S3 bucket name, IAM role
+- **`domains`** — list of domains to create Route53 A records for, all pointing to the EC2 host IP
+- **`env`** — environment variables written to `/etc/environment` on the EC2 host at boot time. **These are never uploaded to S3.**
+
+To add or change environment variables, update the `env` block in `platforms.json` and redeploy. To add a new domain, add it to `domains` and redeploy.
+
 ## Bootstrapping a new host
 
-CDK provisions the instance and starts all three services automatically. The only manual step is setting required environment variables on the host before the first start:
+CDK provisions the instance, writes all service files, writes `/etc/environment` from `platforms.json`, and starts all services automatically. No manual SSH steps required.
 
 ```bash
-# SSH in and edit /etc/environment:
-sudo tee -a /etc/environment << 'EOF'
-DB_URL=mongodb+srv://...
-DB_NAME=ossy
-TOKEN_SECRET=...
-MEDIA_REPOSITORY=...
-MEDIA_CDN_DOMAIN_NAME=...
-AWS_ACCESS_KEY_ID=...
-AWS_SECRET_ACCESS_KEY=...
-OSSY_API_KEY=...
-EOF
-
-# Restart services to pick up the new env vars
-sudo systemctl restart ossy-api ossy-runtime
+cd packages/deployment-tools
+npx cdk deploy ossybot-deployment-target --require-approval never
 ```
 
-> Note: `OSSY_API_KEY` is used by the runtime to authenticate CMS reads. It should be a long-lived API token issued by the API itself.
+> Note: EC2 user data only runs on **first boot**. To apply infrastructure changes to an existing instance you must terminate and recreate it, or SSH in and apply the changes manually.
 
 ## Redeploying after a code change
 
-Both services pull the latest image from GHCR on every restart — no manual build step needed.
+All services pull the latest image from GHCR on every restart — no manual build step needed.
 
 ```bash
-# API — push to main triggers CI, which builds and pushes ghcr.io/ossy-se/api:latest
+# API — push to main triggers CI → ghcr.io/ossy-se/api:latest
 sudo systemctl restart ossy-api
 
-# Runtime — merging to main in the ossy monorepo publishes npm packages and then
-# builds and pushes ghcr.io/ossy-se/platform:latest
+# Platform runtime — merge to main in ossy monorepo → ghcr.io/ossy-se/platform:latest
 sudo systemctl restart ossy-runtime
+
+# website-ossy — push to main in website-ossy repo → ghcr.io/ossy-se/website-ossy:latest
+sudo systemctl restart ossy-website-ossy
+
+# website-plexus-sanitas — push to main → ghcr.io/ossy-se/website-plexus-sanitas:latest
+sudo systemctl restart ossy-website-plexus-sanitas
 ```
 
 ## Environment variables
 
-Service env vars are read from `/etc/environment` on the host. Set these before starting the services:
+All env vars are defined in the `env` block of `platforms.json` and written to `/etc/environment` at boot. Reference:
 
 | Variable | Used by | Description |
 |---|---|---|
@@ -81,17 +85,20 @@ Service env vars are read from `/etc/environment` on the host. Set these before
 | `MEDIA_CDN_DOMAIN_NAME` | API | CloudFront domain for public media |
 | `AWS_ACCESS_KEY_ID` | API | AWS credentials for S3 |
 | `AWS_SECRET_ACCESS_KEY` | API | AWS credentials for S3 |
-| `OSSY_API_KEY` | Runtime | API JWT for CMS reads |
+| `OSSY_API_KEY` | Platform, websites | API JWT for CMS reads |
+| `OSSY_COOKIE_SECRET` | Websites | Cookie signing secret |
+| `OPENAI_API_KEY` | Worker | OpenAI API key |
+| `OPENAI_ORGANIZATION` | Worker | OpenAI organisation ID |
 
 ## Infrastructure (CDK)
 
-CDK stacks are defined in `src/infrastructure/`. Run from `src/infrastructure/cli.js` via `cdk deploy`.
+CDK stacks are defined in `src/infrastructure/`. Run via `cdk deploy` from the `deployment-tools` package.
 
 | Stack | Description |
 |---|---|
 | `trust-ci` | IAM role for CI to deploy infrastructure |
 | `deployment-target` | EC2 host, S3 bucket, CloudFront CDN for media |
-| `dns` | Route53 records |
+| `dns` | Route53 A records for all domains in `platforms.json` |
 | `ses` | SES email sending |
 
 ## Useful commands
@@ -105,6 +112,7 @@ ssh -i path/to/keys ubuntu@<ip>
 ```bash
 journalctl -u ossy-runtime.service -n 200 -f
 journalctl -u ossy-api.service -n 200 -f
+journalctl -u ossy-website-ossy.service -n 200 -f
 journalctl -u caddy-route53.service -n 200 -f
 ```
 
@@ -117,6 +125,7 @@ docker ps
 ```bash
 docker logs ossy-runtime
 docker logs ossy-api
+docker logs ossy-website-ossy
 ```
 
 **Reload Caddy config**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ossy/deployment-tools",
-  "version": "1.17.11",
+  "version": "1.18.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",
@@ -26,5 +26,5 @@
   "devDependencies": {
     "jest": "^27.5.1"
   },
-  "gitHead": "c50aee3d73f8c3f71ce2d8a91e9be2de90c6c4d9"
+  "gitHead": "624e5273e14f3c3db768c9ecae2c7fe27e75f65a"
 }

package/src/config/platform-config.js

@@ -3,14 +3,14 @@
  * @typedef {Object} PlatformConfig
  * @property {string} platformName - Name of platform
  * @property {string[]=} sesDomains - list of domains to configure AWS SES email identity and DKIM records for
+ * @property {string[]=} domains - list of domains to create Route53 A records for, pointing to the EC2 host
  * @property {object} dnsRecords - map of dns records by root domain, only supports MX records so that we can add dns records for our email service
+ * @property {Record<string,string>=} env - environment variables written to /etc/environment on the EC2 host at boot time; never uploaded to S3
  *
  * @property {string} awsAccountId - Aws account id
  * @property {string=} awsRegion - ?
  * @property {string=} awsKeyPairName - ?
  * @property {string} awsRoleToAssume - ?
- * @property {string=} awsDeploymentSqsName - ?
- * @property {string=} awsDeploymentSqsArn - ?
  *
  * @property {string=} ciDockerNetworkName - ?
  * @property {string} ciGithubActionsRepo - organisation/repoName
@@ -20,11 +20,6 @@ const SupportedRegions = {
   North: 'eu-north-1'
 }
 
-const SupportedDeploymentTypes = {
-  Container: 'CONTAINER',
-  Static: 'STATIC'
-}
-
 /**
   * @class
 */
@@ -40,15 +35,8 @@ class PlatformConfigService {
       ciDockerNetworkName: 'deployment-tools',
     }
 
-    const awsDeploymentSqsName = `${withDefaults.platformName}-container-deployments-requests`
-
-    const awsDeploymentSqsArn =
-      `https://sqs.${withDefaults.awsRegion}.amazonaws.com/${withDefaults.awsAccountId}/${awsDeploymentSqsName}`
-
     return {
       ...withDefaults,
-      awsDeploymentSqsName,
-      awsDeploymentSqsArn
     }
 
   }
@@ -58,5 +46,4 @@ class PlatformConfigService {
 module.exports = {
   PlatformConfigService,
   SupportedRegions,
-  SupportedDeploymentTypes
 }

package/src/infrastructure/cli.js

@@ -5,16 +5,13 @@ const { TrustCiStack } = require('./trust-ci-stack')
 const { DeploymentTargetStack } = require('./deployment-target-stack')
 const { DnsStack } = require('./dns-stack')
 const { SesStack } = require('./ses-stack')
-const { PlatformTemplateService, DeploymentTemplateService } = require('../template')
+const { PlatformTemplateService } = require('../template')
 const { PlatformConfigService } = require('../config')
 
-Promise.all([
-  DeploymentTemplateService.readFromFiles('../infrastructure/deployments.json'),
-  PlatformTemplateService
-    .readFromFile('../infrastructure/platforms.json')
-    .then(templates => templates.map(PlatformConfigService.from))
-])
-  .then(([deploymentMap, configs]) => {
+PlatformTemplateService
+  .readFromFile('../infrastructure/platforms.json')
+  .then(templates => templates.map(PlatformConfigService.from))
+  .then(configs => {
     const app = new App()
 
     configs.forEach(config => {
@@ -33,7 +30,6 @@ Promise.all([
 
       new DnsStack(app, `${config.platformName}-dns`, {
         ...stackProps,
-        deployments: deploymentMap[config.platformName],
         containerDeploymentTargetPublicIp: deploymentTarget.containerDeploymentTargetPublicIp
       })
 

package/src/infrastructure/container-deployment-target/container-deployment-target.js

@@ -71,7 +71,7 @@ class ContainerDeploymentTarget extends Construct {
     )
 
     const platformConfigDeployment = new BucketDeployment(this, 'PlatformConfigDeployment', {
-      sources: [Source.jsonData('platform-config.json', { ...props.config, awsRoleToAssume: undefined })],
+      sources: [Source.jsonData('platform-config.json', { ...props.config, awsRoleToAssume: undefined, env: undefined })],
       destinationBucket: props.bucket,
       // Default prune:true would delete every other object (e.g. media/*) on each infra deploy.
       prune: false
@@ -108,6 +108,9 @@ class ContainerDeploymentTarget extends Construct {
 
     const userData = UserData.forLinux()
 
+    // Write platform env vars to /etc/environment so all systemd services pick them up.
+    const envLines = Object.entries(props.config.env ?? {}).map(([k, v]) => `${k}=${v}`)
+
     userData.addCommands(
       'sudo groupadd docker',
       'sudo usermod -aG docker ubuntu',
@@ -118,6 +121,8 @@ class ContainerDeploymentTarget extends Construct {
       ...getInstallDocker(),
       'sudo apt-get install awscli --yes',
       ...AwsProfile.writeFile(role.roleArn, SupportedRegions.North),
+      // Write all platform env vars before starting any service
+      `sudo tee /etc/environment << 'ENVEOF'\n${envLines.join('\n')}\nENVEOF`,
       // Create shared Docker network for inter-container communication
       'docker network create ossy-network || true',
       ...CaddyService.install(),

package/src/infrastructure/container-deployment-target/ossy-runtime.service.js

@@ -12,6 +12,7 @@ ExecStart=/usr/bin/docker run --name ossy-runtime \\
   --network ossy-network \\
   -p 3000:3000 \\
   -e OSSY_API_KEY=\${OSSY_API_KEY} \\
+  -e OSSY_API_URL=http://ossy-api:3001/api/v0 \\
   ghcr.io/ossy-se/platform:latest
 ExecStop=/usr/bin/docker stop ossy-runtime
 Restart=on-failure

package/src/infrastructure/dns-stack.js

@@ -5,22 +5,15 @@ const {
   MxRecord,
   RecordTarget
 } = require('aws-cdk-lib/aws-route53')
-const { SupportedDeploymentTypes } = require('../config')
-const { DeploymentTemplateService } = require('../template')
 
 /**
  * DnsStackProps
  * @namespace DnsStack
  * @typedef {Object} DnsStackProps
  * @property {PlatformConfig} config - platform config
- * @property {PlatformConfig} deployments - deployment templates[]
- * @property {string} containerDeploymentTargetPublicIp - public ip address of ec2 instance that hosts our containerss
+ * @property {string} containerDeploymentTargetPublicIp - public ip address of ec2 instance
  */
 
-const InstanceImages = {
-  UBUNTU: 'ami-092cce4a19b438926'
-}
-
 /**
   * @class
 */
@@ -29,57 +22,56 @@ class DnsStack extends Stack {
   /**
    * @param {object} scope - scope
    * @param {string} id - id
-   * @param {ContainerServerProps} props - ContainerServerProps
+   * @param {DnsStackProps} props - DnsStackProps
    */
   constructor(scope, id, props) {
     super(scope, id, props)
 
-    const containerDeployments = DeploymentTemplateService
-      .getContainerDeployments(props.deployments)
-
-    DeploymentTemplateService
-      .groupDeploymentDomainsByRootDomain(containerDeployments)
-      .forEach((domains, rootDomain) => {
-        const zone = HostedZone.fromLookup(this, `${rootDomain}-zone`, { domainName: rootDomain })
-
-        domains.forEach(domain => {
-          new ARecord(this, `${domain}-record`, {
-            zone,
-            recordName: domain,
-            target: RecordTarget.fromIpAddresses(props.containerDeploymentTargetPublicIp),
-            ttl: Duration.seconds(60)
-          })
+    // Group domains by root domain so we can look up each hosted zone once.
+    const domainsByRoot = (props.config.domains ?? []).reduce((map, domain) => {
+      const parts = domain.split('.')
+      const rootDomain = parts.slice(-2).join('.')
+      map.has(rootDomain)
+        ? map.set(rootDomain, [...map.get(rootDomain), domain])
+        : map.set(rootDomain, [domain])
+      return map
+    }, new Map())
+
+    domainsByRoot.forEach((domains, rootDomain) => {
+      const zone = HostedZone.fromLookup(this, `${rootDomain}-zone`, { domainName: rootDomain })
+
+      domains.forEach(domain => {
+        new ARecord(this, `${domain}-record`, {
+          zone,
+          recordName: domain,
+          target: RecordTarget.fromIpAddresses(props.containerDeploymentTargetPublicIp),
+          ttl: Duration.seconds(60)
         })
+      })
 
-        if (props.config.dnsRecords && props.config.dnsRecords[rootDomain]) {
-          const records = props.config.dnsRecords[rootDomain] || []
-
-          records.forEach(({ type, ttl, recordName, values }) => {
-            switch (type) {
-
-              case 'MX':
-                new MxRecord(
-                  this,
-                  `${recordName}-MX-Record`,
-                  { type, recordName, values, ttl: Duration.seconds(ttl), zone }
-                )
-                break
+      if (props.config.dnsRecords && props.config.dnsRecords[rootDomain]) {
+        const records = props.config.dnsRecords[rootDomain] || []
 
-              default:
-                throw new Error(`Unsupported record type: ${type}`)
-            }
-          })
-        }
+        records.forEach(({ type, ttl, recordName, values }) => {
+          switch (type) {
 
-      })
+            case 'MX':
+              new MxRecord(
+                this,
+                `${recordName}-MX-Record`,
+                { type, recordName, values, ttl: Duration.seconds(ttl), zone }
+              )
+              break
 
+            default:
+              throw new Error(`Unsupported record type: ${type}`)
+          }
+        })
+      }
+    })
   }
 }
 
-function createDnsRecords(zone, records) {
-
-}
-
 module.exports = {
   DnsStack
 }

package/src/template/index.js

@@ -1,4 +1,3 @@
 module.exports = {
-  ...require('./deployment-template'),
   ...require('./platform-template')
 }

package/src/template/deployment-template.js

@@ -1,83 +0,0 @@
-const { glob } = require('glob')
-const { readFileSync } = require('fs')
-const { SupportedDeploymentTypes } = require('../config')
-
-/**
- * Deployment template definition
- * @typedef {Object} DeploymentTemplate
- * @property {string} type - CONTAINER | STATIC
- * @property {string} domain - example.com
- * @property {string} targetDeploymentPlatform - name of platform to deploy to
- *
- * @property {string} image - name of image to be deployed
-  * @property {string} registry -  registry where the image is hosted
- * @property {string=} hostPort - host port
- * @property {string=} containerPort - port that the container exposes
- */
-
-/**
-  * Utility class that helps you read and validate platfor templates from file system
-  * @class
-  */
-class DeploymentTemplateService {
-
-  /**
-   *  Read and and group deployments by targetDeploymentPlatform
-   *
-   * @param {string} blob - blob pattern for deployments.json files
-   */
-   static readFromFiles(blob) {
-     return glob(blob, { ignore: 'node_modules/**' })
-       .then(filePaths => filePaths
-           .map(path => readFileSync(path, 'utf-8'))
-           .flatMap(json => JSON.parse(json))
-           .map(deploymentTemplate => ({
-             containerPort: '3000',
-             ...deploymentTemplate
-           }))
-           .reduce((deploymentsMap, deployment) => {
-             if (!!deploymentsMap[deployment.targetDeploymentPlatform]) {
-               return {
-                 ...deploymentsMap,
-                 [deployment.targetDeploymentPlatform]: [
-                   ...deploymentsMap[deployment.targetDeploymentPlatform],
-                   deployment
-                 ]
-               }
-             }
-
-             return {
-               ...deploymentsMap,
-               [deployment.targetDeploymentPlatform]: [deployment]
-             }
-
-           }, {})
-       )
-   }
-
-  static getContainerDeployments(deployments) {
-    return deployments
-      .filter(deployment => deployment.type === SupportedDeploymentTypes.Container)
-  }
-
-   static groupDeploymentDomainsByRootDomain(deployments) {
-     return deployments
-       .map(deployment => deployment.domain)
-       .reduce((domainGroups, domain) => {
-         const [topLevelDomain, domainName] = domain.split('.').reverse()
-         const rootDomain = `${domainName}.${topLevelDomain}`
-
-         domainGroups.has(rootDomain)
-           ? domainGroups.set(rootDomain, [...domainGroups.get(rootDomain), domain])
-           : domainGroups.set(rootDomain, [domain])
-
-         return domainGroups
-       }, new Map())
-   }
-
-
-}
-
-module.exports = {
-  DeploymentTemplateService
-}