@ossy/deployment-tools 1.20.0 → 1.21.0

package/CHANGELOG.md

@@ -3,6 +3,28 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# 1.21.0 (2026-05-26)
+
+
+### Features
+
+* **business-strategy:** Add comprehensive business strategy document ([408a820](https://github.com/ossy-se/ossy/commit/408a820e7b86019faba178596cc759bd88b4a620))
+
+
+
+
+
+## 1.20.1 (2026-05-26)
+
+
+### Bug Fixes
+
+* **deployment-tools:** Update Caddy service setup and Ubuntu AMI version ([6b3f4f7](https://github.com/ossy-se/ossy/commit/6b3f4f755901450be744d4402ec1f314418d101e))
+
+
+
+
+
 # 1.20.0 (2026-05-25)
 
 

package/README.md

@@ -49,7 +49,11 @@ Additional services are generated automatically from the `services` array in `pl
 
 ### `services` — container/domain mapping
 
-Each entry in `services` generates a systemd unit that pulls and runs a Docker image, and a Caddy block that routes a domain to it. All variables from `env` are forwarded to the container via `--env-file /etc/environment`.
+Services come in two flavours: **HTTP** (routed through Caddy) and **TCP/UDP** (raw socket, bypasses Caddy). Both generate a systemd unit that pulls the image on every restart and forwards `/etc/environment` to the container.
+
+#### HTTP service (default)
+
+Generates a Caddy reverse-proxy block with Route53 TLS. The container must listen on port 3000.
 
 ```json
 "services": [
@@ -63,11 +67,35 @@ Each entry in `services` generates a systemd unit that pulls and runs a Docker i
 
 | Field | Description |
 |---|---|
-| `name` | Unique service name. Used as the Docker container name and systemd unit name (`<name>.service`). |
-| `domain` | Domain this service handles. Gets its own Caddy block with Route53 TLS. |
+| `name` | Unique service name — Docker container name and systemd unit (`<name>.service`). |
+| `domain` | Hostname routed by Caddy to this container (Route53 TLS via `dns route53`). |
 | `image` | Docker image to pull and run. |
 
-Host ports are auto-assigned starting at `3002` based on the order in the array (`services[0]` → `3002`, `services[1]` → `3003`, etc.). Appending new entries is safe; avoid reordering existing ones.
+Host ports are auto-assigned starting at `3002`, counting only HTTP services (TCP entries are skipped). Appending new HTTP entries is safe; avoid reordering existing ones.
+
+#### TCP/UDP service
+
+No Caddy block. Ports are mapped directly (`HOST:CONTAINER`) and opened in the EC2 security group. Use this for game servers or any raw socket protocol.
+
+```json
+"services": [
+  {
+    "name": "minecraft",
+    "type": "tcp",
+    "image": "itzg/minecraft-server",
+    "ports": [25565],
+    "protocol": "tcp"
+  }
+]
+```
+
+| Field | Description |
+|---|---|
+| `name` | Unique service name — Docker container name and systemd unit. |
+| `type` | Must be `"tcp"` to enable this mode. |
+| `image` | Docker image to pull and run. |
+| `ports` | Array of port numbers to expose on the host and open in the security group. |
+| `protocol` | `"tcp"` (default), `"udp"`, or `"both"`. |
 
 **Fixed built-in services** (always present, not configurable via `services`):
 - `ossy-api` — the Ossy API (`ghcr.io/ossy-se/api:latest`, port 3001)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ossy/deployment-tools",
-  "version": "1.20.0",
+  "version": "1.21.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",
@@ -22,5 +22,5 @@
   "devDependencies": {
     "jest": "^27.5.1"
   },
-  "gitHead": "50d7e273859b6b77606d8530913b971c7445a34a"
+  "gitHead": "6eb721d6fa63b333f4b8f8e9b4178f721ecaa531"
 }

package/src/config/platform-config.js

@@ -5,7 +5,20 @@
  * @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 {Array<{name: string, domain: string, image: string}>=} services - per-platform container services; each entry generates a systemd unit and a Caddy domain block. Host ports are auto-assigned starting at 3002.
+ * @property {Array<HttpServiceConfig|TcpServiceConfig>=} services - per-platform container services; each entry generates a systemd unit. HTTP services also get a Caddy reverse-proxy block. TCP/UDP services get direct port exposure and security group rules instead.
+ *
+ * @typedef {Object} HttpServiceConfig
+ * @property {'http'} [type]    - defaults to 'http' when omitted
+ * @property {string} name      - unique service name (container + systemd unit)
+ * @property {string} domain    - hostname routed by Caddy to this container
+ * @property {string} image     - Docker image (e.g. ghcr.io/ossy-se/website-ossy:latest)
+ *
+ * @typedef {Object} TcpServiceConfig
+ * @property {'tcp'} type       - marks a raw socket service; bypasses Caddy entirely
+ * @property {string} name      - unique service name (container + systemd unit)
+ * @property {string} image     - Docker image (e.g. itzg/minecraft-server)
+ * @property {number[]} ports   - ports to open on the host and in the EC2 security group
+ * @property {'tcp'|'udp'|'both'} [protocol] - defaults to 'tcp'
  * @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

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

@@ -21,7 +21,6 @@ api.ossy.se {
   tls {
     dns route53 {
       max_retries 10
-      profile ci-client
     }
   }
   reverse_proxy localhost:3001
@@ -33,7 +32,6 @@ ${serviceBlocks}
     on_demand
     dns route53 {
       max_retries 10
-      profile ci-client
     }
   }
   reverse_proxy localhost:3000
@@ -83,7 +81,8 @@ class CaddyService {
       `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
+      // Create caddy system user (apt install caddy may not run on all Ubuntu versions)
+      'sudo useradd --system --home /var/lib/caddy --shell /usr/sbin/nologin --create-home caddy || true',
       '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

@@ -21,8 +21,7 @@ const { getInstallNodeJs, getInstallNpm, getInstallDocker } = require('./user-da
 const { CaddyService } = require('./caddy.service')
 const { OssyRuntimeService } = require('./ossy-runtime.service')
 const { OssyApiService } = require('./ossy-api.service')
-const { ContainerService } = require('./container-service')
-const { AwsProfile } = require('./aws-profile')
+const { fromConfig: buildContainerServices } = require('./container-service')
 const { SupportedRegions } = require('../../config')
 
 /**
@@ -34,7 +33,7 @@ const { SupportedRegions } = require('../../config')
  */
 
 const InstanceImages = {
-  UBUNTU: 'ami-092cce4a19b438926'
+  UBUNTU: 'ami-067bcf851477ebb78' // Ubuntu Server 24.04 LTS (HVM), eu-north-1
 }
 
 /**
@@ -71,6 +70,16 @@ class ContainerDeploymentTarget extends Construct {
       'allow HTTPS traffic from anywhere'
     )
 
+    // Build container services from config — opens additional security group ports for TCP/UDP services
+    const containerServices = buildContainerServices(props.config.services)
+
+    containerServices.forEach(service => {
+      service.securityGroupPorts.forEach(({ port, protocol }) => {
+        const portRule = protocol === 'udp' ? Port.udp(port) : Port.tcp(port)
+        securityGroup.addIngressRule(Peer.anyIpv4(), portRule, `${service.name} ${protocol.toUpperCase()} ${port}`)
+      })
+    })
+
     const platformConfigDeployment = new BucketDeployment(this, 'PlatformConfigDeployment', {
       sources: [Source.jsonData('platform-config.json', { ...props.config, env: undefined })],
       destinationBucket: props.bucket,
@@ -112,9 +121,6 @@ class ContainerDeploymentTarget extends Construct {
     // 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}`)
 
-    // Build generic container services from config.services
-    const containerServices = ContainerService.fromConfig(props.config.services)
-
     userData.addCommands(
       'sudo groupadd docker',
       'sudo usermod -aG docker ubuntu',
@@ -124,12 +130,11 @@ class ContainerDeploymentTarget extends Construct {
       ...getInstallNpm(),
       ...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(containerServices),
+      ...CaddyService.install(containerServices.filter(s => s.caddyBlock !== null)),
       ...OssyRuntimeService.install(),
       ...OssyApiService.install(),
       ...containerServices.flatMap(s => s.install())

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

@@ -1,34 +1,34 @@
 /**
- * ContainerServiceConfig
- * @typedef {Object} ContainerServiceConfig
- * @property {string} name   - Unique service name, used for the container name and systemd unit
- * @property {string} domain - Domain this service is reachable on (used in Caddy block)
- * @property {string} image  - Docker image to run (e.g. ghcr.io/ossy-se/website-ossy:latest)
- */
-
-const BASE_PORT = 3002 // 3000 = platform runtime, 3001 = API
-
-/**
- * ContainerService generates a systemd unit file and a Caddy reverse-proxy block
- * for a domain → Docker container mapping defined in platforms.json `services`.
+ * @typedef {'http'|'tcp'} ServiceType
+ *
+ * @typedef {Object} HttpServiceConfig
+ * @property {'http'} [type]   - defaults to 'http'
+ * @property {string} name     - unique name, used for container name and systemd unit
+ * @property {string} domain   - domain this service handles (Caddy block + Route53)
+ * @property {string} image    - Docker image to run
  *
- * Host ports are auto-assigned starting at 3002 based on the service's index in
- * the array. All containers are expected to listen on port 3000 internally.
+ * @typedef {Object} TcpServiceConfig
+ * @property {'tcp'} type      - marks this as a raw TCP/UDP service (no HTTP/Caddy)
+ * @property {string} name     - unique name, used for container name and systemd unit
+ * @property {string} image    - Docker image to run
+ * @property {number[]} ports  - ports to expose directly (same inside and outside container)
+ * @property {'tcp'|'udp'|'both'} [protocol] - defaults to 'tcp'
  *
- * All environment variables from /etc/environment are forwarded to the container
- * via --env-file, so no per-service env wiring is needed.
+ * @typedef {HttpServiceConfig|TcpServiceConfig} ContainerServiceConfig
  */
-class ContainerService {
 
-  /**
-   * @param {ContainerServiceConfig} config
-   * @param {number} index - position in the services array, used to derive host port
-   */
-  constructor({ name, domain, image }, index) {
+const BASE_HTTP_PORT = 3002 // 3000 = platform runtime, 3001 = API
+
+// ---------------------------------------------------------------------------
+// HTTP service — reverse-proxied through Caddy, container listens on port 3000
+// ---------------------------------------------------------------------------
+
+class HttpContainerService {
+  constructor({ name, domain, image }, httpIndex) {
     this.name = name
     this.domain = domain
     this.image = image
-    this.port = BASE_PORT + index
+    this.hostPort = BASE_HTTP_PORT + httpIndex
   }
 
   get systemdUnitFile() {
@@ -44,7 +44,7 @@ ExecStartPre=-/usr/bin/docker rm -f ${this.name}
 ExecStartPre=/usr/bin/docker pull ${this.image}
 ExecStart=/usr/bin/docker run --name ${this.name} \\
   --network ossy-network \\
-  -p ${this.port}:3000 \\
+  -p ${this.hostPort}:3000 \\
   --env-file /etc/environment \\
   ${this.image}
 ExecStop=/usr/bin/docker stop ${this.name}
@@ -62,40 +62,101 @@ ${this.domain} {
   tls {
     dns route53 {
       max_retries 10
-      profile ci-client
     }
   }
-  reverse_proxy localhost:${this.port}
+  reverse_proxy localhost:${this.hostPort}
 }`
   }
 
-  get unitName() {
-    return `${this.name}.service`
+  /** Ports to open in the EC2 security group. HTTP services use Caddy on 80/443 — no extra rules needed. */
+  get securityGroupPorts() {
+    return []
   }
 
-  install() {
-    return [`sudo tee /etc/systemd/system/${this.unitName} > /dev/null << 'EOF'\n${this.systemdUnitFile}\nEOF`]
-  }
+  get unitName() { return `${this.name}.service` }
+  install() { return [`sudo tee /etc/systemd/system/${this.unitName} > /dev/null << 'EOF'\n${this.systemdUnitFile}\nEOF`] }
+  enable()  { return [`sudo systemctl enable ${this.name}`] }
+  start()   { return [`sudo systemctl start ${this.name}`] }
+}
+
+// ---------------------------------------------------------------------------
+// TCP/UDP service — bypasses Caddy, ports exposed directly on the host.
+// Used for game servers and any other raw socket services.
+// ---------------------------------------------------------------------------
 
-  enable() {
-    return [`sudo systemctl enable ${this.name}`]
+class TcpContainerService {
+  constructor({ name, image, ports, protocol = 'tcp' }) {
+    this.name = name
+    this.image = image
+    this.ports = ports
+    this.protocol = protocol // 'tcp' | 'udp' | 'both'
   }
 
-  start() {
-    return [`sudo systemctl start ${this.name}`]
+  get systemdUnitFile() {
+    const portMappings = this.ports.map(p => `-p ${p}:${p}`).join(' \\\n  ')
+    return `
+[Unit]
+Description=Container service: ${this.name} (${this.protocol.toUpperCase()} ${this.ports.join(', ')})
+After=network.target docker.service
+Requires=docker.service
+
+[Service]
+EnvironmentFile=/etc/environment
+ExecStartPre=-/usr/bin/docker rm -f ${this.name}
+ExecStartPre=/usr/bin/docker pull ${this.image}
+ExecStart=/usr/bin/docker run --name ${this.name} \\
+  --network ossy-network \\
+  ${portMappings} \\
+  --env-file /etc/environment \\
+  ${this.image}
+ExecStop=/usr/bin/docker stop ${this.name}
+Restart=on-failure
+RestartSec=5
+
+[Install]
+WantedBy=multi-user.target
+`
   }
 
-  /**
-   * Build ContainerService instances from the `services` array in platforms.json.
-   * @param {ContainerServiceConfig[]} services
-   * @returns {ContainerService[]}
-   */
-  static fromConfig(services = []) {
-    return services.map((s, index) => new ContainerService(s, index))
+  /** TCP services bypass Caddy — no Caddy block. */
+  get caddyBlock() { return null }
+
+  /** Each port needs an explicit security group ingress rule. */
+  get securityGroupPorts() {
+    return this.ports.flatMap(port => {
+      if (this.protocol === 'both') return [{ port, protocol: 'tcp' }, { port, protocol: 'udp' }]
+      return [{ port, protocol: this.protocol }]
+    })
   }
 
+  get unitName() { return `${this.name}.service` }
+  install() { return [`sudo tee /etc/systemd/system/${this.unitName} > /dev/null << 'EOF'\n${this.systemdUnitFile}\nEOF`] }
+  enable()  { return [`sudo systemctl enable ${this.name}`] }
+  start()   { return [`sudo systemctl start ${this.name}`] }
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Build service instances from the `services` array in platforms.json.
+ * HTTP services auto-assign host ports starting at 3002 (counted separately
+ * from TCP services so reordering TCP entries doesn't shift HTTP ports).
+ *
+ * @param {ContainerServiceConfig[]} services
+ * @returns {(HttpContainerService|TcpContainerService)[]}
+ */
+const fromConfig = (services = []) => {
+  let httpIndex = 0
+  return services.map(s => {
+    if (s.type === 'tcp') return new TcpContainerService(s)
+    return new HttpContainerService(s, httpIndex++)
+  })
 }
 
 module.exports = {
-  ContainerService
+  HttpContainerService,
+  TcpContainerService,
+  fromConfig
 }

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

@@ -10,7 +10,7 @@ ExecStartPre=-/usr/bin/docker rm -f ossy-api
 ExecStartPre=/usr/bin/docker pull ghcr.io/ossy-se/api:latest
 ExecStart=/usr/bin/docker run --name ossy-api \\
   --network ossy-network \\
-  -p 3001:3001 \\
+  -p 3001:3000 \\
   -e DB_URL=\${DB_URL} \\
   -e DB_NAME=\${DB_NAME} \\
   -e TOKEN_SECRET=\${TOKEN_SECRET} \\