feat: add virtual workstation setup scripts for Linux and Windows

[crowecawcaw]

Fixes: #266

What was the problem/requirement? (What/Why)

Issue #266 asks for an example of pre-configuring a workstation for Deadline Cloud submission, so that an artist who logs in only has to sign in. Setting one up by hand means clicking through two installers, wiring a DCC plugin into per-user application preferences, and completing a monitor sign-in dialog. There was no sample showing how to do that unattended.

What was the solution? (How)

Two example scripts, one for Linux and one for Windows, under utility_scripts/virtual_workstation/. Each takes the monitor URL as its only required argument and:

1. Installs Blender from an official release archive.
2. Installs the Deadline Cloud submitter with its silent installer, resolved from the published submitter manifest so the download is a pinned, checksummed artifact rather than a moving "latest" URL.
3. Enables the submitter's Blender add-on. The silent install stages the add-on but cannot enable it, because add-ons live in Blender's per-user preferences while the install runs at system scope.
4. Installs Deadline Cloud monitor.
5. Creates a monitor profile non-interactively with deadline-cloud-monitor create-profile.

Every download is verified against a published SHA-256 checksum, and an unreachable checksum is an error rather than a reason to skip the check. The scripts call no AWS APIs and need no credentials.

Blender is a stand-in for whichever DCC you run, chosen because it installs unattended from a public archive with no license server, which keeps the example runnable as-is. Adapting to Maya, Nuke, Houdini, 3ds Max, Cinema 4D, After Effects, or VRED means changing three marked places, called out in comments in both scripts and in the README.

Three behaviors are worth flagging for reviewers, because they are not obvious from the installers alone:

• create-profile exits 0 even when it fails. Both scripts check its stdout for the success string and read back the [profile ...] stanza it should have written.
• --monitor-id must be non-empty, but need not be correct. The monitor filters its profile picker on that value and drops any profile whose value is falsy, so an empty ID silently defeats the whole point: the artist gets asked for the monitor URL. The real ID cannot be discovered without AWS credentials, so the scripts pass pending-first-login, which the monitor replaces with the authoritative value at first sign-in.
• A monitor URL without its Region segment is accepted by the monitor and produces a profile with a wrong region=, so both scripts validate the URL shape themselves first.

What is the impact of this change?

Additive: four new files and two modified. No existing sample is touched. The utility_scripts/ category table gains one row per CONTRIBUTING.md, and the static-check suite gains coverage for utility_scripts/ scripts: tests/conftest.py gets a discovery function and tests/test_utility_scripts.py runs bash -n and the PowerShell parser over them. Previously nothing under utility_scripts/ was syntax-checked in CI, though host_configuration_scripts/ was.

Scope limits, all stated in the README rather than left implicit: the Linux script targets Ubuntu 22.04, because the monitor's .deb depends on libwebkit2gtk-4.0-37, which 24.04 replaced with the 4.1 build, and no official repository offers the 4.0 build for it; both require an image that already has a desktop environment, remote access to reach it, and a working default browser; and on Windows the script must run as the artist's own account, because Windows cannot write another user's per-user state without that user's password.

How was this change tested?

Verified end to end on real EC2 instances against a real monitor, on both platforms, including a manual interactive sign-in and an authenticated API call.

Linux — Ubuntu 22.04 EC2 instance with an XFCE desktop, reached over VNC through an SSM tunnel. Ran the script, then signed in to the monitor by hand.

Before sign-in:

monitor_id=pending-first-login
user_id=
identity_store_id=
{"profile_name": "crowest-us-west-2", "status": "NEEDS_LOGIN", "api_availability": false}

After sign-in, the monitor replaced all three with authoritative values:

user_id=f8115370-70f1-70c2-f3a8-9f857c830818
identity_store_id=d-9267dc065a
monitor_id=monitor-ad9b8cfa2a32417ebb9d44567c5eb0ca
{"profile_name": "crowest-us-west-2", "status": "AUTHENTICATED", "api_availability": true}

$ deadline farm list
- region: us-west-2
  farmId: farm-3ce486c2f12a4f9584afe381615364d1
  displayName: crowest farm

Windows — Windows Server 2022 EC2 instance reached over RDP through an SSM tunnel, script run as the artist with elevation. Same result: monitor opened straight to sign-in with no URL prompt, and after signing in, monitor_id became monitor-ad9b8cfa2a32417ebb9d44567c5eb0ca, auth status reported AUTHENTICATED, and deadline farm list returned the farm.

Both instances were in private subnets with no inbound rules, reachable only through SSM port forwarding, and have been deleted.

Also tested

• Full runs in containers on both platforms, with independent post-hoc assertions rather than trusting the scripts' own output: blender --version, the add-on read back from bpy.context.preferences.addons.keys(), deadline --version on the artist's login PATH, and the profile stanza in ~/.aws/config.
• Checksum verification: a real archive against a multi-file manifest, a deliberately corrupted file, an unreachable checksum URL, and a filename absent from the manifest.
• Error paths: no arguments, a monitor URL with no Region segment, a non-apt image, and an image whose repositories lack libwebkit2gtk-4.0-37.
• Static analysis: shellcheck and PSScriptAnalyzer both clean, plus python3 scripts/validate_repository.py, python3 scripts/check_external_links.py, and Vale.

Not tested: submitting an actual job from Blender. Everything up to and including authenticated API calls is verified.

Review round: defects found and fixed after the original testing

Checking the scripts' assumptions against live package indexes and the monitor's own .deb metadata found three defects, each since fixed and re-verified end to end on fresh instances.

• The stated scope was wrong, and the failure mode was bad. The monitor's .deb declares Depends: libwebkit2gtk-4.0-37. Launchpad shows that package is published up to Ubuntu 22.04 only; later releases carry libwebkit2gtk-4.1-0. "Debian-family" therefore over-promised: on Ubuntu 24.04 the script installed Blender and the submitter before failing at apt dependency resolution. There is now an up-front check that stops before installing anything. It uses apt-cache policy rather than apt-cache show, which also succeeds for a virtual package. The supported scope is now Ubuntu 22.04 alone: Debian 12 was listed for a while, but it was never tested, so claiming it was not something this change could back up.
• One download skipped verification. libssl1.1 was fetched and installed with no checksum, the sole exception to a rule the README states twice. It is not published with a .sha256 beside it, so the expected hash is now a pinned constant, with a comment naming the Packages.gz index to read a newer one from.
• The pinned OpenSSL was unpatched. It was 1.1.1f-1ubuntu2, the original 20.04 release, superseded in focal-security by 1.1.1f-1ubuntu2.24. Now on the patched build.

Confirmed the OpenSSL 1.1 requirement is real rather than inherited folklore: strings on /usr/bin/deadline-cloud-monitor shows libssl.so.1.1, and the .deb declares no SSL dependency, which is exactly why a missing library does not fail the install and instead surfaces at first launch.

Also replaced the Blender mirror. It pointed at one volunteer host (mirrors.iu13.net); it now uses Blender's own redirector, mirror.blender.org, verified to serve both the archive and the .sha256 manifest for Linux and Windows.

Re-verified on fresh EC2 instances in a private subnet with no public IP and no inbound rules, reachable only through SSM port forwarding, on Ubuntu 22.04 and Windows Server 2022. Both exited 0. Independent post-hoc assertions rather than the scripts' own output: blender --version, the add-on read back from bpy.context.preferences.addons.keys() as the artist, deadline --version on the artist's login PATH, the profile stanza with a non-empty monitor_id, and deadline auth status reporting NEEDS_LOGIN. Interactive sign-in then completed by hand on both platforms: the monitor opened straight to sign-in with no URL prompt. Both instances have been deleted.

Second review round: silent-failure fixes and verified documentation

A further review pass, plus automated review on the PR, found defects that a passing run hides. Each was reproduced before fixing.

• The Windows script reported success while doing nothing useful when run as SYSTEM. #Requires -RunAsAdministrator is satisfied by SYSTEM, which Systems Manager Run Command and EC2 user data both run as, and every check still passed because they all read the invoking user's own state. The README documented the consequence; nothing enforced it. It now refuses, verified on a real instance: exit 1 with nothing created.
• The Blender version check reintroduced a SIGPIPE bug on both platforms. blender --version | head -1 under pipefail, and & $blenderExe --version | Select-Object -First 1 on Windows, both let the consumer's early exit determine the reported status, so a working Blender could be reported as unable to run. Both now capture the full output and narrow it only for the message. Caught by automated review, which was right to flag it as the same class of defect the libssl check had just been fixed for.
• Two URL validators disagreed. [System.Uri] parses the host out of any scheme, so Windows accepted http://, ftp://, and file:// and would write a non-HTTPS URL into the artist's profile, while Linux rejected the uppercase form Windows accepted. Both now check the scheme and compare in lowercase, and agree on all seven inputs tested.
• rm -rf / Remove-Item -Recurse -Force ran unconditionally as root or administrator on a prefix constant the README tells readers to edit. Both now refuse a directory that holds no Blender executable.
• A Blender that installed but could not start was reported as success, and --enable-components hardcoded deadline_cloud_for_blender outside the three places marked as needing changes, so following the adaptation instructions still installed the Blender submitter.
• Windows left roughly 1 GB of installers in %TEMP%, where Linux traps and removes them. Now removed on success, and deliberately kept on failure so installer logs survive.

Every factual claim in the README was then checked against the real artifacts rather than left as inference. That corrected the cleanup steps (the Linux uninstaller exits 0 but leaves THIRD_PARTY_LICENSES behind), removed advice to add a repository that does not exist for libwebkit2gtk-4.0-37 on newer releases, and noted that deadline auth login is not an alternative to the monitor since it drives the monitor and accepts only monitor-created profiles.

Re-verified end to end on fresh Ubuntu 22.04 and Windows Server 2022 instances in a private subnet with no public IP and no inbound rules: both exited 0, Linux twice for idempotency, the Windows SYSTEM guard exited 1 creating nothing, and hiding a real DT_NEEDED library confirmed the version check still catches a genuinely broken Blender rather than having been neutered by the exit-status change. All instances have been deleted.

Was this change documented?

Yes. utility_scripts/virtual_workstation/README.md covers prerequisites, how it works, what the profile contains and why its fields start empty, adapting to another DCC, what ends up on the machine, security and cleanup, and troubleshooting for the failures this testing actually produced. utility_scripts/README.md gains the category table row and a short section, per CONTRIBUTING.md.

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[phil-IO-p]

The Windows script refuses to run as SYSTEM (line 91), and the comment there makes a convincing case: the profile and Blender preferences are per-user, so a service account produces a workstation where the artist finds nothing configured. Would it be worth adding the mirror-image check here?

As written, WORKSTATION_USER on line 84 falls back to the invoking user, which is root under EC2 user data. That's the path the header on line 13 and the README on line 17 both recommend, and I think every verification step downstream would still pass, since each one reads root's own state. The profile would land in /root/.aws/config and the script would report success, but the artist wouldn't see a pre-configured monitor.

Something like refusing when WORKSTATION_USER resolves to root unless it was passed explicitly would close the gap and match the reasoning already in the Windows script. Happy to be told I'm wrong if there's a provisioning flow where configuring root is the intent.

[phil-IO-p]

The pipefail reasoning in the comment above this block is a nice catch, and I think one more instance of it bites the diagnostic itself. When ldd exits non-zero, that failure propagates through the pipeline into the missing= assignment, and under set -e the script exits right there, so neither the "missing shared libraries" message nor the fallback on line 223 gets printed. I tried the construct standalone and got exit 1 with no output.

The case I'd expect to hit it is arm64: the archive name is pinned to linux-x64, so on Graviton the download and checksum both succeed and the binary fails to exec, which is exactly when ldd says "not a dynamic executable" and exits 1. An || true on that line would keep both messages intact. Would an early uname -m check also be worth it, so an arm64 host fails before the download rather than after?

[phil-IO-p]

Reading #Requires -RunAsAdministrator together with the SYSTEM refusal, I think this implies the artist's own account has to be a local administrator, since it must run elevated as that account. Would it be worth calling that out in Prerequisites?

The case I'm thinking of is a studio where artists are standard users. There the interactive route isn't available, and I don't think the scheduled task with /RU <artist> /RL HIGHEST helps either, since it still needs an account that can elevate. Line 28 currently says "an elevated PowerShell session on Windows," which reads as satisfiable by any admin. Naming whose account it has to be would let people tell early whether the sample fits how they manage workstations.

[phil-IO-p]

The refuse-to-delete guard makes sense, and I want to flag one interaction with the comment above it. If a run is interrupted partway through the tar -xJf, /opt/blender is left holding a partial extraction that probably has no ./blender in it yet, since tar's member order isn't guaranteed. Every later run then trips the guard and stops with "exists but holds no blender executable," so the script can't get past it without someone removing the directory by hand.

Extracting into a temp directory and then moving it into place would mean the prefix only ever exists complete, which keeps the guard doing its job while making re-runs clean the way the comment describes. Alternatively, a line in Troubleshooting about clearing the prefix would at least give the operator the recovery step. The Windows script has the same shape around line 184, though the staged extract there makes it less likely.

[phil-IO-p]

One thing I wasn't able to test, so treat it as a question rather than a finding: in Windows PowerShell 5.1, 2>&1 on a native command turns stderr lines into error records, and with $ErrorActionPreference = "Stop" that becomes a terminating NativeCommandError. If a Blender build ever writes a startup warning to stderr (a GPU or driver notice, say), I think this line would fail with a .NET error rather than reaching your check on line 208.

It clearly didn't come up in your Windows Server 2022 testing, so blender --version must be quiet there. It just seems to depend on the Blender build rather than on anything the script controls. Would wrapping it in try/catch, or relaxing $ErrorActionPreference around just this call, be worth the insurance?

[phil-IO-p]

nit: Regarding error messages rather than behavior... in both of these spots the specific message underneath can't actually be reached, because the statement above it throws first under EAP=Stop.

On line 192, if Expand-Archive yields no top-level directory, .FullName is $null and Move-Item -Path $null throws a parameter-binding error before the "expected blender.exe at ..." check runs. Same shape on line 356: a missing .aws\config makes Select-String throw path-not-found rather than reaching your "profile is missing from" message. Capturing the directory and testing it before the move, plus a Test-Path before Select-String, would let both messages actually surface. Either way the script fails, so purely a nicer-diagnostics thing.

[phil-IO-p]

Would you add a row to the table in tests/README.md for test_utility_scripts.py? Right now the table lists every other area, so someone adding a script under utility_scripts/ would read it and conclude nothing validates theirs.

The part I'd find most useful there is the bit already explained in the module docstring: these get the same bash -n and PowerShell parse checks, but the scriptBody limit deliberately doesn't apply because they aren't uploaded to the service. That contrast with the host configuration row is the thing a future contributor would otherwise have to work out from the source.

[phil-IO-p]

nit: This says "before anything is installed," but apt-get install ca-certificates curl xz-utils python3 five lines up has already run by then. The check is still well placed, since it comes before the monitor, submitter, and Blender, which are the parts that actually cost time to undo. Maybe "before the monitor or submitter are installed"? The comments in these scripts are precise enough that I found myself reading this one literally.