@ossy/deployment-tools

Collection of scripts and tools to aid deployment of containers and static files to Amazon Web Services (typically from CI).

Server

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.

npx @ossy/deployment-tools server start

stop

Stops the deployment-tools systemd service

npx @ossy/deployment-tools server stop

status

Prints the status of the deployment-tools systemd service

npx @ossy/deployment-tools server status

Deployment

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).

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).

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.

deploy (single domain)

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"

| 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 |

deploy-all (whole platform)

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"

Apps: use @ossy/cli publish

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.

Useful commands

SSH into instance

ssh -i path/to/keys ubuntu@<ip>

View running containers

docker ps

View logs from docker container

docker logs <id|alias>

View logs from deployment-tools service

// With last 200 lines and follow new logs
journalctl -u deployment-tools.service -n 200 -f

View logs from caddy service

// With last 200 lines and follow new logs
journalctl -u caddy-route53.service -n 200 -f

View logs from docker service

// With last 200 lines and follow new logs
journalctl -u docker.service -n 200 -f

Upgrade deployment-tools server version

• 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

That's it, the service will download the latest version of the package.

Update Nodejs on the server

# 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 -

# Install Node.js 24
sudo apt-get install -y nodejs

# Verify the installation
node --version
npm --version