Cylc 8.7.0

In the AWS Marketplace listing, choose Continue to Subscribe, then Continue to Configuration. Pick Cylc 8.7.0 on Ubuntu 24.04 as the software version and select your Region, then choose Launch through EC2.

Choose m5.large (or larger for big workflows), your key pair, and a security group as described above. Workflow run directories live under /var/lib/cylc/cylc-run on the root volume, so size the root volume for the logs and outputs that your workflows keep.

Alternatively, launch with the AWS CLI. Replace the values in angle brackets:

aws ec2 run-instances --image-id <ami-id-from-the-listing> --instance-type m5.large \
  --key-name <your-key-pair> --security-group-ids <your-security-group> --subnet-id <your-subnet> \
  --metadata-options HttpTokens=required,HttpEndpoint=enabled \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=cylc}]'

First boot takes a few seconds after the instance is running.

To make the instance use your own name from the start, put the name in /etc/sac/cylc-domain.preset with user data (for example a cloud-init write_files entry). Otherwise, first boot uses the instance's public IP address (or its private address if it has no public one). It also serves the instance's EC2 public DNS name and its private address.

Connect over SSH. The operating system is Ubuntu 24.04, and the SSH user is ubuntu:

ssh -i <your-key.pem> ubuntu@<public-ip>

The login message shows the address of the Cylc UI and where the password is.

systemctl is-active sac-cylc-guard cylc-uiserver nginx

active active active

The cylc-firstboot service runs once, on the first boot, and shows inactive on every later boot.

Only SSH, HTTP and HTTPS are public. The UI Server listens on the loopback address:

sudo ss -tln | grep -E ':(22|80|443|8890|8080|4300[0-9]|430[1-9][0-9]|4310[01]) '

LISTEN 0 4096 0.0.0.0:22 0.0.0.0:* LISTEN 0 511 0.0.0.0:80 0.0.0.0:* LISTEN 0 511 0.0.0.0:443 0.0.0.0:* LISTEN 0 128 127.0.0.1:8890 0.0.0.0:* LISTEN 0 4096 [::]:22 [::]:* LISTEN 0 511 [::]:80 [::]:* LISTEN 0 511 [::]:443 [::]:*

Run the built-in self-test. It signs in through nginx with this instance's password and checks that a request without a session and a wrong password are refused. It then runs a GraphQL query and a websocket subscription:

sudo cylc-selftest

cylc-selftest: unauthenticated UI/profile/version/GraphQL/websocket and ?token= refused; wrong password 401 (no login cookie); signed in as cylc (24 permissions); GraphQL 0 workflow(s); websocket connection_ack CYLC_SELFTEST_OK

The address and certificate fingerprint are in /root/cylc-credentials.txt (root only, mode 0600). Show everything except the password:

sudo grep -v '^CYLC_PASSWORD=' /root/cylc-credentials.txt

# Cylc 8.7.0 (sac) on this instance. Open CYLC_URL in a browser and sign in with CYLC_PASSWORD (password only).
# The password is unique to this instance. Change it:
sudo cylc-set-password (or --stdin to choose one).
# The certificate is self-signed for this instance: compare its SHA-256 fingerprint with CYLC_TLS_SHA256.
# Workflows run as the cylc account:
sudo -iu cylc (sources ~/cylc-src, runs ~/cylc-run) CYLC_URL=https://198.51.100.24/cylc/ CYLC_HOST=198.51.100.24 CYLC_TLS_SHA256=09:BC:CE:DE:62:BD:7C:B7:29:91:C7:B3:3F:2D:F5:12:F8:08:94:CC:09:97:76:06:AC:31:20:1F:93:F9:87:49 CYLC_ADDRESS_SOURCE=imdsv2-public-ipv4 GUIDE=https://secureanycloud.com/stacks/cylc-8-7-0/

The password is on the CYLC_PASSWORD line. Show it only when you are ready to copy it. Do not paste it into a ticket, a chat or a shell history:

sudo grep '^CYLC_PASSWORD=' /root/cylc-credentials.txt

The certificate is self-signed and unique to your instance, so your browser warns about it. Open the certificate details in the browser, check that its SHA-256 fingerprint matches CYLC_TLS_SHA256, and only then continue.

Do not add the certificate to your operating system's trust store. For production, replace it with a certificate from a certificate authority (Step 11).

Copy the certificate to your home directory so that the commands in this guide can use it as their trust anchor:

sudo cat /etc/ssl/cylc/cylc.crt > ~/cylc-instance.crt openssl x509 -in ~/cylc-instance.crt -noout -subject -ext basicConstraints,keyUsage,extendedKeyUsage,subjectAltName

subject=CN = 198.51.100.24, O = sac X509v3 Subject Alternative Name: IP Address:198.51.100.24, DNS:ec2-198-51-100-24.compute-1.amazonaws.com, IP Address:172.31.10.20, DNS:localhost, IP Address:127.0.0.1 X509v3 Basic Constraints: critical CA:FALSE X509v3 Key Usage: critical Digital Signature, Key Encipherment X509v3 Extended Key Usage: TLS Web Server Authentication

Browse to the CYLC_URL address. The UI Server's sign-in page asks for the password only.

Enter the password from Step 4. A wrong password is refused and gives no session. After 6 attempts in a minute from the same address, nginx answers 429 Too Many Requests until the minute has passed.

The session cookie is Secure, HttpOnly and SameSite=Lax. It stays valid for 31 days or until you change the password (Step 10). Browsing to /logout on the instance's address removes it from that browser.

The UI opens on the workflow list. A new instance has no workflows yet, and Step 6 runs one.

Workflows are run by the cylc account. Open a shell as cylc. Its home is /var/lib/cylc, workflow sources go in ~/cylc-src, and runs go in ~/cylc-run:

sudo -iu cylc

The commands below run the same steps without an interactive shell. sudo -iu cylc starts in the cylc home, so ./cylc-src/... is the workflow source there. Give Cylc a path such as ./cylc-src/<name> for a source directory, because Cylc reads a bare name as an installed workflow.

First write an example workflow. It has three cycle points, six hours apart. Each cycle fetches observations, runs a model that also depends on the previous cycle's model run, publishes a product and tidies up:

sudo -iu cylc bash -c 'mkdir -p ~/cylc-src/sac-demo && cat > ~/cylc-src/sac-demo/flow.cylc' <<'EOF' [scheduler] UTC mode = True allow implicit tasks = False [scheduling] initial cycle point = 20260101T0000Z final cycle point = 20260101T1200Z [[graph]] PT6H = """ get_observations => run_model => publish_products => housekeep run_model[-PT6H] => run_model """ [runtime] [[get_observations]] script = sleep 10; echo "observations for ${CYLC_TASK_CYCLE_POINT}" [[run_model]] script = sleep 20; echo "model run for ${CYLC_TASK_CYCLE_POINT}" [[publish_products]] script = """ sleep 5 mkdir -p "${CYLC_WORKFLOW_SHARE_DIR}/products" echo "forecast valid ${CYLC_TASK_CYCLE_POINT}" > "${CYLC_WORKFLOW_SHARE_DIR}/products/forecast-${CYLC_TASK_CYCLE_POINT}.txt" """ [[housekeep]] script = sleep 3 EOF
sudo -iu cylc cylc validate ./cylc-src/sac-demo || { echo "FATAL: the workflow did not validate"; exit 1; }

Install the workflow, which creates a new run directory at ~/cylc-run/sac-demo/run1, and start its scheduler:

sudo -iu cylc cylc install ./cylc-src/sac-demo || { echo "FATAL: cylc install failed"; exit 1; }
sudo -iu cylc cylc play sac-demo || { echo "FATAL: cylc play failed"; exit 1; }

INSTALLED sac-demo/run1 from /var/lib/cylc/cylc-src/sac-demo ▪ ■ Cylc Workflow Engine 8.7.0 ██ Copyright (C) 2008-2026 Earth Sciences New Zealand ▝▘ & British Crown (Met Office) & Contributors INFO - Extracting job.sh to /var/lib/cylc/cylc-run/sac-demo/run1/.service/etc/job.sh sac-demo/run1: ip-172-31-10-20.ec2.internal PID=4934

Go back to the browser. The dashboard counts one running workflow, and the run appears in the workflow list on the left as sac-demo/run1.

Click sac-demo/run1 to open it. The Tree view shows each active cycle point, its tasks and their states (waiting, preparing, submitted, running, succeeded), updated live over the UI's websocket.

A little later, the run has moved on. In the first cycle point, the model run has succeeded and publish_products is running. The second cycle point's model run, which waited for the first one, is now running.

The run takes about two minutes. Wait for the scheduler to finish, then look at what it produced:

for i in $(seq 1 60); do
sudo -iu cylc cylc scan --states=running --format=name | grep -q '^sac-demo/' || break; sleep 5; done
sudo -iu cylc bash -c 'cat ~/cylc-run/sac-demo/runN/share/products/forecast-*.txt' \
  || { echo "FATAL: the workflow published no products"; exit 1; }
sudo -iu cylc cylc cat-log sac-demo//20260101T1200Z/run_model | tail -3

forecast valid 20260101T0000Z forecast valid 20260101T0600Z forecast valid 20260101T1200Z 2026-11-08T09:43:30Z INFO - started model run for 20260101T1200Z 2026-11-08T09:43:50Z INFO - succeeded

When you no longer need a run, remove its run directory:

sudo -iu cylc cylc clean --yes sac-demo || { echo "FATAL: cylc clean failed"; exit 1; }

Put each workflow in its own directory under ~cylc/cylc-src with a flow.cylc file. Then run cylc validate, cylc install and cylc play on it as above. The Cylc documentation covers the workflow language, cycling, retries, events and every command.

Everyday commands:

sudo -iu cylc cylc scan
# running workflows
sudo -iu cylc cylc tui <workflow>
# the terminal UI
sudo -iu cylc cylc pause <workflow>
# stop submitting new jobs
sudo -iu cylc cylc play <workflow>
# resume, or restart a stopped run
sudo -iu cylc cylc stop <workflow>
# stop once running jobs finish
sudo -iu cylc cylc trigger <workflow>//<cycle>/<task>

Things to know on this image:

• Run workflows as cylc. The UI shows and controls the cylc account's workflows only. The account is a plain user: tasks cannot use sudo, and the operating system directories are read-only to them.
• Starting from the UI or from SSH. A workflow that you start with cylc play over SSH keeps running if the UI Server restarts. A workflow that you start or restart from the UI runs inside the UI Server's service, so it stops when the UI Server restarts (for example, when you change the password). Run cylc play <workflow> over SSH to resume it where it stopped.
• The UI shows one operator. This is a single-user appliance, so whoever has the password has full control of every cylc workflow. Cylc's multi-user authorization (user_authorization) applies only behind a hub, so it is left empty here.

As shipped, the only job platform is this instance (localhost, background jobs), configured in /etc/cylc/flow/global.cylc.

To run tasks on an HPC login node or a batch system, define a platform in that file (or in ~cylc/.cylc/flow/global.cylc). For example, this defines a Slurm cluster reached over SSH:

[platforms] [[hpc]] hosts = login1.hpc.example.com job runner = slurm install target = hpc

Then complete these three actions:

• Give the cylc account an SSH key that the remote account accepts (sudo -iu cylc ssh-keygen -t ed25519, and add ~cylc/.ssh/id_ed25519.pub to the remote account's authorized_keys), and check sudo -iu cylc ssh login1.hpc.example.com true.
• Install Cylc 8.7.0 (cylc-flow) on the remote host, as the platform documentation describes.
• Remote jobs report back to the scheduler on its ZMQ ports (43001-43101, set in global.cylc). The image refuses those ports from the network. To accept them from the remote hosts only, open them in your security group for those hosts. Then add an accept rule for their addresses before the refusal in the input chain of /etc/sac/cylc-guard.nft, for example ip saddr 203.0.113.0/24 tcp dport 43001-43101 accept, and run sudo systemctl restart sac-cylc-guard. Alternatively, set the platform's communication method = poll so that remote jobs never connect back.

The image blocks the instance metadata service for the cylc account: the UI Server, every scheduler and every task. This stops a workflow task (or any code that tricks a task into making a request) from reading the instance role's temporary credentials.

Check the block:

sudo -iu cylc curl -s -m 5 -o /dev/null -w 'cylc account -> metadata service: %{http_code}\n' -X PUT \
  -H 'X-aws-ec2-metadata-token-ttl-seconds: 60' http://169.254.169.254/latest/api/token || true curl -s -m 5 -o /dev/null -w 'ubuntu account -> metadata service: %{http_code}\n' -X PUT \
  -H 'X-aws-ec2-metadata-token-ttl-seconds: 60' http://169.254.169.254/latest/api/token

cylc account -> metadata service: 000 ubuntu account -> metadata service: 200

The value 000 means the connection was refused.

If your tasks must call AWS services, prefer credentials scoped to the workflow, for example an ~cylc/.aws/credentials profile for a dedicated IAM user or a role assumed with aws sts assume-role.

If you decide that the tasks may use the instance role, remove the block for the cylc account. Delete the two meta skuid lines that name 169.254.169.254 and fd00:ec2::254 from the output chain of /etc/sac/cylc-guard.nft. Alternatively, keep www-data in them and remove only the cylc uid. Leave the third line, the reserved ranges, in place. Then run sudo systemctl restart sac-cylc-guard.

For workflows started from the UI, also add a drop-in that replaces the UI Server's own block with the reserved ranges only:

sudo systemctl edit cylc-uiserver
# add these three lines, save, then: [Service] IPAddressDeny= IPAddressDeny=192.0.0.0/24 198.18.0.0/15 224.0.0.0/4 240.0.0.0/4
sudo systemctl restart cylc-uiserver

Attach an instance role with only the permissions the workflows need.

Generate a new random password (written to /root/cylc-credentials.txt), or choose one of at least 12 characters. The command reads a chosen password from standard input, so it never appears on a command line:

sudo cylc-set-password read -rs P && printf '%s\n' "$P" | sudo cylc-set-password --stdin; unset P

The UI Server restarts with the new hash, and every existing browser session is signed out. Workflows that were started from the UI stop with the restart (the command says so if there are any). Resume them with sudo -iu cylc cylc play <workflow>.

Point a DNS name at the instance, then make it the instance's name. The command writes the nginx host names (requests for any other name are dropped), generates a new self-signed certificate for the names, and restarts nginx:

sudo cylc-set-domain cylc.example.com

To use a certificate from a certificate authority instead, put the full chain and key in /etc/ssl/cylc/cylc.crt and /etc/ssl/cylc/cylc.key (root only, mode 0600 for the key). Then run sudo nginx -t && sudo systemctl reload nginx.

If the instance's public address changes after a stop and start, run cylc-set-domain again with the new address.

To reach the UI without opening port 443, use an SSH tunnel: ssh -L 8443:127.0.0.1:443 ubuntu@<public-ip>. Then browse to https://localhost:8443/cylc/.

sudo -iu cylc cylc version --long | head -3 cat /usr/share/doc/cylc/README.sac

8.7.0 (/opt/cylc/venv/bin/cylc) Plugins: Cylc on this image (sac) ============================= cylc-flow 8.7.0 GPL-3.0-or-later https://github.com/cylc/cylc-flow cylc-uiserver 1.10.0 GPL-3.0-or-later https://github.com/cylc/cylc-uiserver cylc-ui 2.15.0 GPL-3.0-or-later https://github.com/cylc/cylc-ui (the web UI bundle inside cylc-uiserver) All three are shipped UNMODIFIED, installed in /opt/cylc/venv from the hash-pinned lock in requirements.lock (every dependency's licence: dependency-licences.txt). The licence texts are COPYING.cylc-flow, COPYING.cylc-uiserver and COPYING.cylc-ui. The corresponding source is in source/: cylc_flow-8.7.0.tar.gz sha256 743cbe7bde84784f91e3d2758dbffe1aa1afedd66ee4015b39a20221ca7c6a67 (https://files.pythonhosted.org/packages/7d/64/c0ab38c5143b648d2638992c980d1bce7f6d4e7a6f05b5af8cc35fd7c427/cylc_flow-8.7.0.tar.gz) cylc_uiserver-1.10.0.tar.gz sha256 b1d5bc0ad433b7e47709784614b3ff946f210654b280c0a25cb9b240ff342810 (https://files.pythonhosted.org/packages/88/52/97dbce50928bb12c8e4863d0fc14662b52e17b46e8aacfe8118ec2250e12/cylc_uiserver-1.10.0.tar.gz) cylc-ui-2.15.0.tar.gz sha256 eb1b1d980f5678ed75fde8d42074d5fa5aef92cbd219da7b8543f3f8a4d939e5 (https://codeload.github.com/cylc/cylc-ui/tar.gz/refs/tags/2.15.0) sac packages and configures Cylc; it does not modify it. Cylc is not endorsed by or affiliated with sac.

Cylc (cylc-flow, cylc-uiserver and cylc-ui) is free software under the GNU General Public License version 3 or later. The image ships it unmodified.

The license texts, the full list of installed Python packages with their versions, hashes and licenses, and the complete corresponding source are in /usr/share/doc/cylc. The Python packages are pinned by SHA-256 in /usr/share/doc/cylc/requirements.lock.

Ubuntu's unattended upgrades keep the operating system, nginx and Python patched. Cylc itself does not update automatically: the SecureAnyCloud listing adds a new version when Cylc releases one.

To keep workflows across a move to a new instance, copy ~cylc/cylc-src (sources) and any run directories that you still need.

Cylc is developed by NIWA, the Met Office and the Cylc community. SecureAnyCloud packages and configures it and is not affiliated with or endorsed by the Cylc project.