Installation

Requirements

  • 2 CPU cores, 512 MB of RAM

For operating system and CPU architecture support, the decisive factors are the capabilities of the provisioners and job runners (GitHub Actions Runner, Jenkins Agent, …​) you plan on using.

Generally, the Node Agent alone should run on any of Rust’s Tier 1 and 2 platforms that have host tools as well as support for std and alloc.

We validate Stretchy Node Agent on Linux and macOS, both on x86, 64 bit and ARM, 64 bit, with a variety of guests.
Validation of macOS on x86, 64 bit is on its last legs. We have a single Mac mini remaining that can run it.

At a Glance

  1. Create a new node in Stretchy Orchestrator.

  2. Install and configure Stretchy Node Agent (see below).

We do not provide a container image with Stretchy Node Agent because all provisioners require direct access to the host.

Archive

Linux

We recommend to run stretchy-agent as a non-privileged user. For the rest of the steps, we assume that the user is named sna. Furthermore, we assume that you already have a created a node in Stretchy Orchestrator with the name linux-host and the password påsswörd1!.

The sample configuration uses unencrypted systemd credentials to pass secrets to stretchy-agent. Please see the systemd documentation on system and service credentials for alternatives that provide higher levels of security.

  1. Download Stretchy Node Agent for the architecture of your system.

  2. Unpack the archive and move its contents to /usr/local/stretchy-orchestrator.

  3. Create a systemd unit in /etc/systemd/system with the name stretchy-agent.service and the contents from Example 1 after replacing the values in angle brackets.

  4. Enable the systemd service by running systemd enable stretchy-agent.service as root.

Example 1. Systemd unit file template for Stretchy Node Agent
[Unit]
Description=Stretchy Node Agent
After=syslog.target network.target

[Service]
User=sna
Group=sna
Type=exec
ExecStart=/usr/local/stretchy-agent/bin/stretchy-agent \
    --orchestrator="wss://stretchy.example.com/ws/agent" \
    --login=linux-host \
    --password-file=%d/password \
    --provisioner=<identifier> \ (1)
    --provisioner-parallelism=<paralleism> \ (2)
LoadCredential=password:/path/to/password
WorkingDirectory=/usr/local/stretchy-agent

[Install]
WantedBy=multi-user.target
1 Specify the identifier of the provisioner to use, see Provisioners.
2 Determines on how many machines the provisioner can work concurrently. 3 is a good value to begin with.
This systemd service configuration is insecure. Please see the section systemd in the chapter Configuration for how to harden the systemd service.
We recommend to instruct systemd to restart stretchy-agent automatically on failure with Restart=. Please see systemd.service(5) for further information.

macOS

We recommend to run stretchy-agent as an unprivileged macOS user (called "Standard" by macOS). For the rest of the steps, we assume that the user is named sna. Furthermore, we assume that you already have a created a node in Stretchy Orchestrator with the name macos-host and the password påsswörd1!.

  1. Download Stretchy Node Agent for the architecture of your system.

  2. Unpack the archive and move its contents to /usr/local/stretchy-agent.

  3. Create a job definition for launchd in /Library/LaunchDaemons with the name dev.stretchy.agent.plist and the contents from Example 2.

  4. Enable the Launch Daemon by running launchctl load /Library/LaunchDaemons/dev.stretchy.agent.plist as root.

Example 2. Job definition for Stretchy Agent
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>dev.stretchy.agent</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/stretchy-agent/bin/stretchy-agent</string>
        <string>--orchestrator</string>
        <string>wss://stretchy.example.com/</string>
        <string>--login</string>
        <string>macos-host</string>
        <string>--password</string>
        <string>påsswörd1!</string>
        <string>--provisioner</string>
        <string>IDENTIFIER</string> (1)
        <string>--provisioner-parallelism</string>
        <string>3</string> (2)
    </array>
    <key>WorkingDirectory</key>
    <string>/usr/local/stretchy-agent</string>
    <key>UserName</key>
    <string>sna</string>
    <key>GroupName</key>
    <string>staff</string>
    <key>KeepAlive</key>
    <true/>
    <key>RunAtLoad</key>
    <true/>
    <key>EnvironmentVariables</key>
    <dict>
        <key>PATH</key> (3)
        <string>/bin:/usr/bin:/usr/local/bin</string>
    </dict>
</dict>
</plist>
1 Replace IDENTIFIER with the identifier of the provisioner you want to use, see Provisioners.
2 Determines on how many machines the provisioner can work concurrently. 3 is a good value to begin with.
3 Define all necessary environment variables. Depending on the provisioner, more variables than PATH might be necessary.