@ossy/deployment-tools 1.17.3 → 1.17.5

package/CHANGELOG.md

@@ -3,6 +3,22 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## 1.17.5 (2026-05-25)
+
+**Note:** Version bump only for package @ossy/deployment-tools
+
+
+
+
+
+## 1.17.4 (2026-05-23)
+
+**Note:** Version bump only for package @ossy/deployment-tools
+
+
+
+
+
 ## 1.17.3 (2026-05-23)
 
 **Note:** Version bump only for package @ossy/deployment-tools

package/README.md

@@ -1,125 +1,125 @@
 # @ossy/deployment-tools
 
-Collection of scripts and tools to aid deployment of
-containers and static files to Amazon Web Services (typically from CI).
+Infrastructure and CDK tooling for the Ossy platform EC2 host.
 
-## Server
+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`
 
-### start
-Starts a node server in the background that polls an deployment queue for container deployment requests.
-Make sure NodeJs and npm is installed and Docker and Caddy is up and running.
-```bash
-npx @ossy/deployment-tools server start
-```
+## Architecture
 
-### stop
-Stops the deployment-tools systemd service
-```bash
-npx @ossy/deployment-tools server stop
 ```
-
-### status
-Prints the status of the deployment-tools systemd service
-```bash
-npx @ossy/deployment-tools server status
+Internet → Caddy (:443)
+             ├── api.ossy.se → ossy-api (:3001)
+             └── *.* (on-demand TLS) → ossy-runtime (:3000)
+                                            └── loads build from CMS on first request
 ```
 
-## Deployment
+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.
 
-The first argument after the package name is the **handler** (`deployment`). Commands are **`deployment deploy`** (one site) and **`deployment deploy-all`** (every deployment entry for a platform).
+## Services
 
-Deployments are read from a **glob** of JSON files (e.g. `deployments.json`), and platform definitions from a **platforms** JSON file. Domain and platform for a given site are **not** taken from `ossy.json`; they live in those deployment records (and, in app workflows, mirror **`domain` / `platform` in `src/config.js`** when you use **`@ossy/cli publish`**).
+All services run as Docker containers managed by systemd. Service files are written to the EC2 host by CDK user data at instance creation.
 
-**Container images must live in Amazon ECR.** Each `CONTAINER` row needs a **`registry`** field with your ECR API endpoint (for example `123456789012.dkr.ecr.eu-north-1.amazonaws.com`). Both the **CLI** (`deployment deploy`) and the **worker** (`server start`) require this. The worker **always** runs **`aws ecr get-login-password | docker login`** before **`docker pull`**, using the host IAM role (or environment AWS credentials). Do not put registry passwords on the queue.
+| Service | Unit file | Port | Auto-start |
+|---|---|---|---|
+| Caddy | `caddy-route53.service` | 80, 443 | Yes |
+| Ossy API | `ossy-api.service` | 3001 | Manual |
+| Ossy Runtime | `ossy-runtime.service` | 3000 | Manual |
 
-### deploy (single domain)
+The API and runtime are **not** auto-started because their Docker images must be built on the host first. After SSHing in and building the images, enable them once:
 
 ```bash
-npx --yes @ossy/deployment-tools deployment deploy \
-  --domain example.com \
-  --platform my-platform \
-  --platforms-path packages/infrastructure/bin/deployment-platforms.json \
-  --deployments-path "packages/infrastructure/deployments/**/*.json"
+sudo systemctl enable --now ossy-api ossy-runtime
 ```
 
-| Flag | Alias | Description |
-|------|--------|-------------|
-| `--domain` | `-d` | Target site domain (must match an entry under that platform in the deployments glob) |
-| `--platform` | `-p` | Target deployment platform name |
-| `--platforms-path` | `-pp` | Path to platforms JSON (AWS / queue config) |
-| `--deployments-path` | `-dp` | Glob of deployment JSON files |
+## Bootstrapping a new host
 
-### deploy-all (whole platform)
+After CDK provisions the EC2 instance (Caddy starts automatically), SSH in and:
 
 ```bash
-npx --yes @ossy/deployment-tools deployment deploy-all \
-  --platform my-platform \
-  --platforms-path packages/infrastructure/bin/deployment-platforms.json \
-  --deployments-path "packages/infrastructure/deployments/**/*.json"
-```
+# Clone the repo
+git clone <repo-url> ~/ossy
+cd ~/ossy
 
-### Apps: use @ossy/cli publish
+# Build the API image
+docker build -t ossy-api:latest -f api/Dockerfile api
 
-For Ossy apps, prefer **`npx @ossy/cli publish`** from the website package: it resolves **`--domain` / `--platform`** from **`src/config.js`** (or **`--config`**) when possible, calls **`deployment deploy`** (or **`deploy-all`** with **`--all`**), then can upload **resource templates** from the same config. See **`packages/cli/README.md`**.
+# Build the runtime image
+docker build -t ossy-runtime:latest \
+  -f packages/runtime/Dockerfile packages/runtime
 
-## Useful commands
+# Start both services
+sudo systemctl enable --now ossy-api ossy-runtime
+```
 
+## Redeploying after a code change
 
-**SSH into instance**
-```
-ssh -i path/to/keys ubuntu@<ip>
-```
+```bash
+cd ~/ossy && git pull
 
-**View running containers**
-```
-docker ps
-```
+# Rebuild whichever image changed
+docker build -t ossy-api:latest -f api/Dockerfile api
+# or
+docker build -t ossy-runtime:latest \
+  -f packages/runtime/Dockerfile packages/runtime
 
-**View logs from docker container**
-```
-docker logs <id|alias>
+# Restart the service
+sudo systemctl restart ossy-api
+# or
+sudo systemctl restart ossy-runtime
 ```
 
-**View logs from deployment-tools service**
-```
-// With last 200 lines and follow new logs
-journalctl -u deployment-tools.service -n 200 -f
-```
+## Environment variables
 
-**View logs from caddy service**
-```
-// With last 200 lines and follow new logs
-journalctl -u caddy-route53.service -n 200 -f
-```
+Service env vars are read from `/etc/environment` on the host. Set these before starting the services:
 
-**View logs from docker service**
-```
-// With last 200 lines and follow new logs
-journalctl -u docker.service -n 200 -f
-```
+| Variable | Used by | Description |
+|---|---|---|
+| `DB_URL` | API | Atlas MongoDB connection string |
+| `DB_NAME` | API | MongoDB database name |
+| `TOKEN_SECRET` | API | JWT signing secret |
+| `MEDIA_REPOSITORY` | API | S3 bucket name for media uploads |
+| `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 |
+
+## Infrastructure (CDK)
 
-**Upgrade deployment-tools server version**
+CDK stacks are defined in `src/infrastructure/`. Run from `src/infrastructure/cli.js` via `cdk deploy`.
 
- - 1 release new version of the npm package with `npm publish`
- - 2 ssh into the instance with `ssh -i path/to/keys ubuntu@<ip>`
- - 3 stop the deployment-tools services with `sudo systemctl stop deployment-tools.service`
- - 4 remove the old version of the tool with `rm -rf ~/.npm/_npx`
- - 5 start the deployment-tools services again with `sudo systemctl start deployment-tools.service`
+| Stack | Description |
+|---|---|
+| `trust-ci` | IAM role for CI to deploy infrastructure |
+| `deployment-target` | EC2 host, S3 bucket, CloudFront CDN for media |
+| `dns` | Route53 records |
+| `ses` | SES email sending |
 
-That's it, the service will download the latest version of the package.
+## Useful commands
+
+**SSH into instance**
+```bash
+ssh -i path/to/keys ubuntu@<ip>
+```
 
-**Update Nodejs on the server**
+**View service logs**
+```bash
+journalctl -u ossy-runtime.service -n 200 -f
+journalctl -u ossy-api.service -n 200 -f
+journalctl -u caddy-route53.service -n 200 -f
 ```
-# Remove old NodeSource repository if it exists
-sudo rm -f /etc/apt/sources.list.d/nodesource.list
 
-# Download and run the Node.js 24.x setup script
-curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
+**View running containers**
+```bash
+docker ps
+```
 
-# Install Node.js 24
-sudo apt-get install -y nodejs
+**View container logs**
+```bash
+docker logs ossy-runtime
+docker logs ossy-api
+```
 
-# Verify the installation
-node --version
-npm --version
+**Reload Caddy config**
+```bash
+sudo systemctl reload caddy-route53.service
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ossy/deployment-tools",
-  "version": "1.17.3",
+  "version": "1.17.5",
   "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",
@@ -28,8 +28,7 @@
     "node-fetch": "^2.6.7"
   },
   "devDependencies": {
-    "jest": "^27.5.1",
-    "jsdoc": "^4.0.2"
+    "jest": "^27.5.1"
   },
-  "gitHead": "f96e3c98e87f9a19b92f7eab0d54e4de12509007"
+  "gitHead": "81baa12dad845ec3f48438d2c4ba139a3a271770"
 }

package/src/index.cli.js

@@ -5,9 +5,7 @@ const [_, __, handlerName, ...restArgs] = process.argv
 
 const loadHandler = {
   aws: () => require('./aws-credentials/cli.js'),
-  deployment: () => require('./deploy/cli.js'),
   template: () => require('./template/cli.js'),
-  server: () => require('./server/cli.js'),
 }[handlerName]
 
 !!loadHandler && loadHandler().handler(restArgs)

package/src/infrastructure/cli.js

@@ -5,7 +5,6 @@ const { TrustCiStack } = require('./trust-ci-stack')
 const { DeploymentTargetStack } = require('./deployment-target-stack')
 const { DnsStack } = require('./dns-stack')
 const { SesStack } = require('./ses-stack')
-const { EcrStack } = require('./ecr-stack')
 const { PlatformTemplateService, DeploymentTemplateService } = require('../template')
 const { PlatformConfigService } = require('../config')
 
@@ -29,10 +28,6 @@ Promise.all([
       }
 
       new TrustCiStack(app, `${config.platformName}-trust-ci`, stackProps)
-      new EcrStack(app, `${config.platformName}-ecr`, {
-        ...stackProps,
-        deployments: deploymentMap[config.platformName] || []
-      })
 
       const deploymentTarget = new DeploymentTargetStack(app, `${config.platformName}-deployment-target`, stackProps)
 

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

@@ -1,12 +1,25 @@
+const caddyfile = `
+{
+  on_demand_tls {
+    ask http://localhost:3001/api/v0/apps/ask
+  }
+}
+
+api.ossy.se {
+  reverse_proxy localhost:3001
+}
+
+:443 {
+  tls {
+    on_demand
+  }
+  reverse_proxy localhost:3000
+}
+`
+
 const systemdServiceFile = `
-# caddy-api.service
-#
-# For using Caddy with its API.
-#
-# This unit is "durable" in that it will automatically resume
-# the last active configuration if the service is restarted.
-#
-# See https://caddyserver.com/docs/install for instructions.
+# caddy-route53.service — Caddy with Route53 DNS plugin for on-demand TLS.
+# Configured via /etc/caddy/Caddyfile.
 
 [Unit]
 Description=Caddy
@@ -18,7 +31,7 @@ Requires=network-online.target
 Type=notify
 User=caddy
 Group=caddy
-ExecStart=/usr/bin/caddy.route53 run --environ --resume
+ExecStart=/usr/bin/caddy.route53 run --config /etc/caddy/Caddyfile
 TimeoutStopSec=5s
 LimitNOFILE=1048576
 LimitNPROC=512
@@ -37,7 +50,12 @@ class CaddyService {
 
   static install() {
     return [
-      `sudo echo "${systemdServiceFile}" >> /etc/systemd/system/caddy-route53.service`,
+      // Write Caddyfile
+      'sudo mkdir -p /etc/caddy',
+      `sudo tee /etc/caddy/Caddyfile > /dev/null << 'CADDYEOF'\n${caddyfile}\nCADDYEOF`,
+      // Write systemd unit
+      `sudo tee /etc/systemd/system/caddy-route53.service > /dev/null << 'UNITEOF'\n${systemdServiceFile}\nUNITEOF`,
+      // Install Caddy + xcaddy + Route53 plugin
       'sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https',
       'sudo curl -1sLf \'https://dl.cloudsmith.io/public/caddy/stable/gpg.key\' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg',
       'sudo curl -1sLf \'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt\' | sudo tee /etc/apt/sources.list.d/caddy-stable.list',

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

@@ -1,4 +1,3 @@
-const { Duration, RemovalPolicy } = require('aws-cdk-lib')
 const { Construct } = require('constructs')
 const {
   Instance,
@@ -15,11 +14,11 @@ const {
   BlockDeviceVolume
 } = require('aws-cdk-lib/aws-ec2')
 const { Role, ServicePrincipal, Policy, PolicyStatement, Effect } = require('aws-cdk-lib/aws-iam')
-const { Queue } = require('aws-cdk-lib/aws-sqs')
 const { Source, BucketDeployment } = require('aws-cdk-lib/aws-s3-deployment')
 const { getInstallNodeJs, getInstallNpm, getInstallDocker } = require('./user-data-commands')
 const { CaddyService } = require('./caddy.service')
-const { DeploymentToolsService } = require('./deployment-tools.service')
+const { OssyRuntimeService } = require('./ossy-runtime.service')
+const { OssyApiService } = require('./ossy-api.service')
 const { AwsProfile } = require('./aws-profile')
 const { SupportedRegions } = require('../../config')
 
@@ -69,11 +68,6 @@ class ContainerDeploymentTarget extends Construct {
       'allow HTTPS traffic from anywhere'
     )
 
-    const deploymentQueue = new Queue(this, 'DeploymentQueue', {
-      queueName: `${props.config.awsDeploymentSqsName}`,
-      receiveMessageWaitTime: Duration.seconds(20)
-    })
-
     const platformConfigDeployment = new BucketDeployment(this, 'PlatformConfigDeployment', {
       sources: [Source.jsonData('platform-config.json', { ...props.config, awsRoleToAssume: undefined })],
       destinationBucket: props.bucket,
@@ -107,16 +101,6 @@ class ContainerDeploymentTarget extends Construct {
           ],
           resources: ['*']
         }),
-        new PolicyStatement({
-          effect: Effect.ALLOW,
-          actions: [
-            'ecr:GetAuthorizationToken',
-            'ecr:BatchGetImage',
-            'ecr:GetDownloadUrlForLayer',
-            'ecr:BatchCheckLayerAvailability'
-          ],
-          resources: ['*']
-        })
       ]
     }))
 
@@ -132,8 +116,11 @@ class ContainerDeploymentTarget extends Construct {
       ...getInstallDocker(),
       'sudo apt-get install awscli --yes',
       ...AwsProfile.writeFile(role.roleArn, SupportedRegions.North),
+      // Create shared Docker network for inter-container communication
+      'docker network create ossy-network || true',
       ...CaddyService.install(),
-      ...DeploymentToolsService.install()
+      ...OssyRuntimeService.install(),
+      ...OssyApiService.install()
     )
 
     userData.addS3DownloadCommand({
@@ -145,9 +132,9 @@ class ContainerDeploymentTarget extends Construct {
     userData.addCommands(
       'sudo systemctl daemon-reload',
       ...CaddyService.enable(),
-      ...DeploymentToolsService.enable(),
-      ...CaddyService.start(),
-      ...DeploymentToolsService.start()
+      ...CaddyService.start()
+      // ossy-runtime and ossy-api are enabled manually after building images:
+      //   sudo systemctl enable --now ossy-runtime ossy-api
     )
 
     const ec2Instance = new Instance(this, 'Ec2Instance', {
@@ -157,7 +144,7 @@ class ContainerDeploymentTarget extends Construct {
       role,
       instanceType: InstanceType.of(
         InstanceClass.T3,
-        InstanceSize.LARGE
+        InstanceSize.SMALL
       ),
       machineImage: new GenericLinuxImage({
         [SupportedRegions.North]: InstanceImages.UBUNTU
@@ -172,7 +159,6 @@ class ContainerDeploymentTarget extends Construct {
     })
 
     props.bucket.grantRead(ec2Instance, '*')
-    deploymentQueue.grant(ec2Instance, '*')
 
     this.instancePublicIp = ec2Instance.instancePublicIp
 

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

@@ -0,0 +1,43 @@
+const systemdServiceFile = `
+[Unit]
+Description=Ossy API
+After=network.target docker.service
+Requires=docker.service
+
+[Service]
+EnvironmentFile=/etc/environment
+ExecStartPre=-/usr/bin/docker rm -f ossy-api
+ExecStart=/usr/bin/docker run --name ossy-api \\
+  --network ossy-network \\
+  -p 3001:3001 \\
+  -e DB_URL=\${DB_URL} \\
+  -e DB_NAME=\${DB_NAME} \\
+  -e TOKEN_SECRET=\${TOKEN_SECRET} \\
+  -e MEDIA_REPOSITORY=\${MEDIA_REPOSITORY} \\
+  -e MEDIA_CDN_DOMAIN_NAME=\${MEDIA_CDN_DOMAIN_NAME} \\
+  -e AWS_ACCESS_KEY_ID=\${AWS_ACCESS_KEY_ID} \\
+  -e AWS_SECRET_ACCESS_KEY=\${AWS_SECRET_ACCESS_KEY} \\
+  ossy-api:latest
+ExecStop=/usr/bin/docker stop ossy-api
+Restart=on-failure
+RestartSec=5
+`
+
+// No [Install] section — service is enabled manually after the image is built.
+// SSH into the host, build the image, then:
+//   sudo systemctl enable --now ossy-api
+
+/**
+  * @class
+*/
+class OssyApiService {
+
+  static install() {
+    return [`sudo tee /etc/systemd/system/ossy-api.service > /dev/null << 'EOF'\n${systemdServiceFile}\nEOF`]
+  }
+
+}
+
+module.exports = {
+  OssyApiService
+}

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

@@ -0,0 +1,37 @@
+const systemdServiceFile = `
+[Unit]
+Description=Ossy Runtime
+After=network.target docker.service
+Requires=docker.service
+
+[Service]
+EnvironmentFile=/etc/environment
+ExecStartPre=-/usr/bin/docker rm -f ossy-runtime
+ExecStart=/usr/bin/docker run --name ossy-runtime \\
+  --network ossy-network \\
+  -p 3000:3000 \\
+  -e OSSY_API_KEY=\${OSSY_API_KEY} \\
+  ossy-runtime:latest
+ExecStop=/usr/bin/docker stop ossy-runtime
+Restart=on-failure
+RestartSec=5
+`
+
+// No [Install] section — service is enabled manually after the image is built.
+// SSH into the host, build the image, then:
+//   sudo systemctl enable --now ossy-runtime
+
+/**
+  * @class
+*/
+class OssyRuntimeService {
+
+  static install() {
+    return [`sudo tee /etc/systemd/system/ossy-runtime.service > /dev/null << 'EOF'\n${systemdServiceFile}\nEOF`]
+  }
+
+}
+
+module.exports = {
+  OssyRuntimeService
+}

package/jsdoc/AwsCredentialsService.html

@@ -1,166 +0,0 @@
-<!DOCTYPE html>
-<html lang="en">
-<head>
-    <meta charset="utf-8">
-    <title>JSDoc: Class: AwsCredentialsService</title>
-
-    <script src="scripts/prettify/prettify.js"> </script>
-    <script src="scripts/prettify/lang-css.js"> </script>
-    <!--[if lt IE 9]>
-      <script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
-    <![endif]-->
-    <link type="text/css" rel="stylesheet" href="styles/prettify-tomorrow.css">
-    <link type="text/css" rel="stylesheet" href="styles/jsdoc-default.css">
-</head>
-
-<body>
-
-<div id="main">
-
-    <h1 class="page-title">Class: AwsCredentialsService</h1>
-
-    
-
-
-
-
-<section>
-
-<header>
-    
-        <h2><span class="attribs"><span class="type-signature"></span></span>AwsCredentialsService<span class="signature">()</span><span class="type-signature"></span></h2>
-        
-    
-</header>
-
-<article>
-    <div class="container-overview">
-    
-        
-
-    
-
-    
-    <h4 class="name" id="AwsCredentialsService"><span class="type-signature"></span>new AwsCredentialsService<span class="signature">()</span><span class="type-signature"></span></h4>
-    
-
-    
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-<dl class="details">
-
-    
-
-    
-
-    
-
-    
-
-    
-
-    
-
-    
-
-    
-
-    
-
-    
-
-    
-
-    
-
-    
-    <dt class="tag-source">Source:</dt>
-    <dd class="tag-source"><ul class="dummy"><li>
-        <a href="aws-credentials_aws-credentials.js.html">aws-credentials/aws-credentials.js</a>, <a href="aws-credentials_aws-credentials.js.html#line9">line 9</a>
-    </li></ul></dd>
-    
-
-    
-
-    
-
-    
-</dl>
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-    
-    </div>
-
-    
-
-    
-
-    
-
-    
-
-    
-
-    
-
-    
-
-    
-
-    
-
-    
-</article>
-
-</section>
-
-
-
-
-</div>
-
-<nav>
-    <h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="AwsCredentialsService.html">AwsCredentialsService</a></li><li><a href="AwsProfile.html">AwsProfile</a></li><li><a href="CaddyService.html">CaddyService</a></li><li><a href="ContainerServer.html">ContainerServer</a></li><li><a href="DeploymentQueueService.html">DeploymentQueueService</a></li><li><a href="DeploymentToolsService.html">DeploymentToolsService</a></li><li><a href="DockerService.html">DockerService</a></li><li><a href="EstablishTrustStack.html">EstablishTrustStack</a></li><li><a href="PlatformConfigService.html">PlatformConfigService</a></li><li><a href="PlatformDeploymentService.html">PlatformDeploymentService</a></li><li><a href="PlatformServerService.html">PlatformServerService</a></li><li><a href="PlatformStack.html">PlatformStack</a></li><li><a href="PlatformTemplateService.html">PlatformTemplateService</a></li><li><a href="RestApiService.html">RestApiService</a></li></ul><h3><a href="global.html">Global</a></h3>
-</nav>
-
-<br class="clear">
-
-<footer>
-    Documentation generated by <a href="https://github.com/jsdoc/jsdoc">JSDoc 3.6.11</a> on Sun Oct 23 2022 22:23:31 GMT+0200 (Central European Summer Time)
-</footer>
-
-<script> prettyPrint(); </script>
-<script src="scripts/linenumber.js"> </script>
-</body>
-</html>