@ossy/deployment-tools 1.21.1 → 1.21.3

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.21.3 (2026-05-26)
+
+**Note:** Version bump only for package @ossy/deployment-tools
+
+
+
+
+
+## 1.21.2 (2026-05-26)
+
+**Note:** Version bump only for package @ossy/deployment-tools
+
+
+
+
+
 ## 1.21.1 (2026-05-26)
 
 **Note:** Version bump only for package @ossy/deployment-tools

package/README.md

@@ -75,7 +75,9 @@ Host ports are auto-assigned starting at `3002`, counting only HTTP services (TC
 
 #### 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.
+No Caddy block. Containers run with **`--network host`** so game servers bind ports on the EC2 instance directly (avoids Docker bridge DNAT issues for public traffic). The `ports` and `protocol` fields still drive **security group** ingress rules — they are not passed as `-p` mappings.
+
+Use this for game servers or any other raw socket protocol.
 
 ```json
 "services": [
@@ -85,6 +87,15 @@ No Caddy block. Ports are mapped directly (`HOST:CONTAINER`) and opened in the E
     "image": "itzg/minecraft-server",
     "ports": [25565],
     "protocol": "tcp"
+  },
+  {
+    "name": "palworld",
+    "type": "tcp",
+    "image": "thijsvanloef/palworld-server-docker",
+    "ports": [
+      { "port": 8211, "protocol": "udp" },
+      { "port": 27021, "protocol": "udp" }
+    ]
   }
 ]
 ```
@@ -94,8 +105,8 @@ No Caddy block. Ports are mapped directly (`HOST:CONTAINER`) and opened in the E
 | `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"`. |
+| `ports` | Port numbers (host network) and security group rules. Use a **number** with service-level `protocol`, or `{ "port": 8211, "protocol": "udp" }` per port when protocols differ. |
+| `protocol` | Default for numeric `ports` entries: `"tcp"` (default), `"udp"`, or `"both"`. Ignored when every port is an object with its own `protocol`. Must match what the game image listens on. |
 
 **Fixed built-in services** (always present, not configurable via `services`):
 - `ossy-api` — the Ossy API (`ghcr.io/ossy-se/api:latest`, port 3001)
@@ -122,6 +133,38 @@ Each platform is a CDK `Stage` containing five stacks:
 
 The Elastic IP ensures the EC2 instance can be replaced (instance type changes, user data updates) without breaking DNS or CloudFormation cross-stack exports.
 
+## Destroy + redeploy
+
+`<platformName>` is the `platformName` field in `packages/infrastructure/platforms.json` (CDK stage id). `<aws-profile>` is your AWS CLI profile for that account. List stacks: `npx cdk list --profile <aws-profile>`.
+
+Full platform teardown:
+
+```bash
+cd packages/deployment-tools
+npx cdk destroy '<platformName>/**' --profile <aws-profile>
+```
+
+Recreate (CDK applies stacks in dependency order):
+
+```bash
+npx cdk deploy '<platformName>/**' --profile <aws-profile>
+```
+
+Recycle **only the EC2 host** (keep S3, CDN, and backups):
+
+```bash
+npx cdk destroy '<platformName>/dns' --profile <aws-profile>
+npx cdk destroy '<platformName>/deployment-target' --profile <aws-profile>
+npx cdk deploy '<platformName>/deployment-target' --profile <aws-profile>
+npx cdk deploy '<platformName>/dns' --profile <aws-profile>
+```
+
+Do not destroy `storage-static` unless you intend to drop media storage (bucket is `RETAIN` and may remain in the account anyway).
+
+The S3 bucket and **AWS Backup vault** use `RETAIN` so media and recovery points survive a stack delete. CloudFront and the backup *plan* are removed with the stack.
+
+If deploy fails with **BackupVault already exists** after a full destroy, a retained vault is still in the account (`<platformName>-static-media-backup`). Delete it in AWS Backup (empty recovery points first), or import it into the new stack.
+
 ## Bootstrapping a new platform
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ossy/deployment-tools",
-  "version": "1.21.1",
+  "version": "1.21.3",
   "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": "5920a30df63c1d67315d83eca0bce77b8e85b7b9"
+  "gitHead": "909e3d78752d07afceb60af78784987f6fcea8b7"
 }

package/src/config/platform-config.js

@@ -17,8 +17,8 @@
  * @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 {(number|{port: number, protocol: 'tcp'|'udp'|'both'})[]} ports - host ports + security group rules
+ * @property {'tcp'|'udp'|'both'} [protocol] - default for numeric ports; 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/container-service.js

@@ -11,14 +11,38 @@
  * @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'
+ * @property {(number|TcpPortEntry)[]} ports - host ports; each entry uses `protocol` or the service default
+ * @property {'tcp'|'udp'|'both'} [protocol] - default for numeric ports; defaults to 'tcp'
+ *
+ * @typedef {Object} TcpPortEntry
+ * @property {number} port
+ * @property {'tcp'|'udp'|'both'} protocol
  *
  * @typedef {HttpServiceConfig|TcpServiceConfig} ContainerServiceConfig
  */
 
 const BASE_HTTP_PORT = 3002 // 3000 = platform runtime, 3001 = API
 
+/**
+ * @param {(number|TcpPortEntry)[]} ports
+ * @param {'tcp'|'udp'|'both'} defaultProtocol
+ * @returns {TcpPortEntry[]}
+ */
+const normalizePortEntries = (ports, defaultProtocol = 'tcp') =>
+  ports.map(entry =>
+    typeof entry === 'number'
+      ? { port: entry, protocol: defaultProtocol }
+      : { port: entry.port, protocol: entry.protocol ?? defaultProtocol }
+  )
+
+/** @param {TcpPortEntry} entry */
+const expandSecurityGroupRules = ({ port, protocol }) => {
+  if (protocol === 'both') {
+    return [{ port, protocol: 'tcp' }, { port, protocol: 'udp' }]
+  }
+  return [{ port, protocol }]
+}
+
 // ---------------------------------------------------------------------------
 // HTTP service — reverse-proxied through Caddy, container listens on port 3000
 // ---------------------------------------------------------------------------
@@ -80,23 +104,23 @@ ${this.domain} {
 }
 
 // ---------------------------------------------------------------------------
-// TCP/UDP service — bypasses Caddy, ports exposed directly on the host.
-// Used for game servers and any other raw socket services.
+// TCP/UDP service — bypasses Caddy, listens on the EC2 host network namespace.
+// Uses --network host so game traffic hits the process directly (no bridge DNAT).
+// Security group ingress still comes from securityGroupPorts below.
 // ---------------------------------------------------------------------------
 
 class TcpContainerService {
   constructor({ name, image, ports, protocol = 'tcp' }) {
     this.name = name
     this.image = image
-    this.ports = ports
-    this.protocol = protocol // 'tcp' | 'udp' | 'both'
+    this.portEntries = normalizePortEntries(ports, protocol)
   }
 
   get systemdUnitFile() {
-    const portMappings = this.ports.map(p => `-p ${p}:${p}`).join(' \\\n  ')
+    const portList = this.portEntries.map(({ port, protocol }) => `${port}/${protocol}`).join(', ')
     return `
 [Unit]
-Description=Container service: ${this.name} (${this.protocol.toUpperCase()} ${this.ports.join(', ')})
+Description=Container service: ${this.name} (host network, ${portList})
 After=network.target docker.service
 Requires=docker.service
 
@@ -105,8 +129,7 @@ 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} \\
+  --network host \\
   --env-file /etc/environment \\
   ${this.image}
 ExecStop=/usr/bin/docker stop ${this.name}
@@ -121,12 +144,9 @@ WantedBy=multi-user.target
   /** TCP services bypass Caddy — no Caddy block. */
   get caddyBlock() { return null }
 
-  /** Each port needs an explicit security group ingress rule. */
+  /** Each port needs an explicit security group ingress rule matching its protocol. */
   get securityGroupPorts() {
-    return this.ports.flatMap(port => {
-      if (this.protocol === 'both') return [{ port, protocol: 'tcp' }, { port, protocol: 'udp' }]
-      return [{ port, protocol: this.protocol }]
-    })
+    return this.portEntries.flatMap(expandSecurityGroupRules)
   }
 
   get unitName() { return `${this.name}.service` }
@@ -158,5 +178,6 @@ const fromConfig = (services = []) => {
 module.exports = {
   HttpContainerService,
   TcpContainerService,
+  normalizePortEntries,
   fromConfig
 }

package/src/infrastructure/storage-static-stack.js

@@ -39,6 +39,7 @@ class StorageStaticStack extends Stack {
     })
 
     const backupVault = new BackupVault(this, 'StaticMediaBackupVault', {
+      backupVaultName: `${props.config.platformName}-static-media-backup`,
       removalPolicy: RemovalPolicy.RETAIN
     })