Getting Started

Once you're ready click here to start your journey!

Welcome to the Bruce Getting Started Guide! This tutorial will help you set up Bruce, understand its core components, and run your first workflow.First we will step into the fundamentals of what makes up this ecosystem, and then we will walk through each of the components, and how it fits together. And finally we will look at downloading and getting started with bruce and also how to connect it directly to the service.

For more detailed documentation on how to use the binary and the bruce application in general, please visit our Documentation Site.

The Ecosystem

Bruce is funadamentally composed of 2 major components in the ecosystem, the open source application which is hosted on github which is available here: Bruce on Github and the server side components which are all running through this "website" as the backend service.

Bruce (Open Source Application)

Bruce (Basic Runtime for Uniform Compute Environments) is a command line application with zero dependencies that run on all major platforms. Bruce as a standalone application makes use of manifest files which are in YAML format to drive the execution of pre-defined user operations. These operations can include extracting files, or setting up configurations with templates etc. At it's core Bruce is an execution engine that takes a manifest as input and executes those commands with minimal, or no need for dependencies. While you similar applications like Ansible that use manifests to log into a remote server to execute commands majority of these types of applications require a large amount of dependencies to execute on the local machine for instance python. Or it requires an actual ssh action which could be a potential security issue. Bruce allows both execution of local manifests in air gapped environments. But also allows for execution directly from remote environments with no dependencies. As a use case we have some clients that provision bruce as a golden image and set the manifest to run on initialization of the server, however the change here is that they point to a secure S3 location that can only be reached by the calling server. That allows the server to be fully self contained and secure with zero userland dependencies.

The Service (Workspace once Logged in)

The service that is provided can be broken down further into 3 core components which are the following:

Agents

An agent within the service defines a specific Bruce application with a default action. This means that if you create an agent in the portal you intend to connect to it, and as such it contains an identifier and key. To clarify this more: Once you download bruce (from github latest releases or our downloads page) you can now set up bruce to run in server mode. When you perform this action you provide bruce with a unique identifier and a key to authenticate with teh server. At this point you are also responsible for creating teh default action within the configuration file, after this you simply run bruce in server mode for instance `bruce server /etc/bruce/default.yml` Bruce will now read the endpoint data, and connect to the server and whenever it receives a command to execute it will go ahead and execute the manifest file that was pre-configured. A agent configuration also allows you to trigger additional actions on success or failure, as well as notifications which will be discussed below.

Actions

Actions extend the functionality of bruce allowing you to specify a new action that will be executed, but you may also define which agents will be responsible for executing the action, allowing you to spread out the work across many agents. This has bene very useful to build and automate complex applications that must be built on different architectures, for instance Windows, Mac and Linux. As an example, we recently helped a client with an unreal engine game project to build and test their application on 3 different platforms with a single commit in their code repository. This greatly increased their speed to market and ensured issues were caught and resolved early. Similar to agents, actions also contain the ability to trigger additional actions on success or failure, this means that if an action is successful you can automatically trigger an additional action on success or failure, like retrieving logs for review, or publishing the application artifacts. This also includes the notifications that go along with success and failures.

Notifications

Notifications make up the last section of the service. This allows you to get interactive notifications via webhooks, discord and other means, on success and failure allowing you to bring the human element back into the workflow should you need it. While notifications are simple they provide the final element required for ensuring your workflows and pipelines are running as expected. This is also the final ingredient in order to create a well defined workflow that is highly scalable and observable.

Downloading the Latest Release

To begin, download the latest release from the Bruce releases page. Each platform-specific zip contains a single binary—no complex installations. Extract the contents, place the binary in your system PATH, and run the following command to verify:

`bruce --help`

This should output:

NAME:
   bruce - Start with: /path/to/bruce https://someinstallhost/installme.yml

USAGE:
   bruce [global options] command [command options]

COMMANDS:
   install, setup  this is the default action and will be run if no commands are specified
   server, svr     this will start the bruce server, allowing the preset config to be run on trigger
   view, open      this command opens the manifest for you to view in CLI prior to executing install
   upgrade         this command will upgrade the bruce application to the latest version
   version         this prints the current version of bruce and the current latest version of bruce
   help, h         Shows a list of commands or help for one command

GLOBAL OPTIONS:
   --config value                   See docs for supported endpoints, eg: https://s3.amazonaws.com/somebucket/my_install.yml (default: "/etc/bruce/config.yml")
   --property-file value, -p value  Loads properties from a file, eg: /etc/bruce/properties.yml to be used as environment variables for operators and templates
   --debug, -d                      Enable debug logging (default: false)
   --help, -h                       show help

Setting Up Your Environment

Bruce works with editors like VS Code, Sublime Text, and Atom. Create a YAML file to start experimenting with configurations. Bruce’s flexibility allows for easy integration into your workflow, and the ability to use Bruce’s advanced cloud capabilities adds even more power to your setup.

Example YAML File

Note: This example sets up Nginx on an Ubuntu system. It's designed for new Ubuntu installations.

Here’s a simple YAML file to install Nginx, configure a virtual host, set up log rotation, and clone a static HTML repository.

            
---
variables:
  ServiceOwner: www-data
  RotateDays: 7
  VHOST_ROOT: /opt/vhosts/hello-world
steps:
- cmd: dnf install -y nginx logrotate

# get my ip address to set as the vhost domain
- cmd: ip addr show $(ip route | awk '/default/ {print $5}') | awk '/inet / {print $2}' | awk -F/ '{print $1}'
  setEnv: Domain

# Create a virtual host via a template
- template: /etc/nginx/sites-available/hello-world
  remoteLocation: https://raw.githubusercontent.com/brucehq/example-setup/refs/heads/main/nginx/hello-world.vhost

# Create a symlink for the virtual host
- cmd: ln -sf /etc/nginx/sites-available/hello-world /etc/nginx/sites-enabled/hello-world

# Clone the static HTML repo
- gitRepo: https://github.com/brucehq/static-content-example.git
  dest: VHOST_ROOT

- template: /etc/logrotate.d/nginx
  remoteLocation: https://raw.githubusercontent.com/brucehq/example-setup/refs/heads/main/nginx/logrotate.tpl

# Enable and start the Nginx service
- cmd: systemctl daemon-reload nginx && systemctl enable nginx && systemctl start nginx

Running the Example

To get access to this source code including the manifest file (nginx.yml) to run this please see: https://github.com/brucehq/example-setup

Operators

In the example above, Bruce uses several operators to streamline the CI/CD process. For a deeper dive into operators and how they can supercharge your pipelines, check out the Bruce Documentation.

Exploring More Operators

Bruce provides a comprehensive set of operators that give you full control over automations, and by leveraging Bruce, you can maximize the impact of your workflows.

Going More Advanced

Bruce also supports server mode, allowing for more complex, event-driven workflows. This mode is especially useful for managing multiple pipelines through a server YAML file:

---
endpoint: wss://bruce.tools/workers
runner-id: 2ce3227b-e14a-4a0b-8021-b5313794f42d
authorization: a4fd4sa9-6c68-5416-b8df-df92ade178ca
execution:
  - name: run all default
    action: default # you must have a default action.
    type: event # can also be cadence
    cadence: 10 # execution in minutes if cadence is chosen
    target: test.yaml # should be the path to the manifest to be executed, in this case main branch example config

Server mode isn't required but gives you flexibility to trigger workflows through cadence or event-driven actions. By connecting to Bruce, you unlock more capabilities like event-based workflows coordinate your local agents into single, or highly complex workflows.

Supercharging Your Experience with Bruce

When you enable Bruce’s event-driven mode, Bruce takes center stage, allowing you to orchestrate and automate multiple pipelines from anywhere. Each event is tied to an action, and with Bruce, your workflow execution becomes highly scalable and dynamic.

With Bruce, you don’t need to keep YAML files locally. Simply upload them to a web server or S3, and Bruce will pull and execute the files on demand. Whether for A/B testing or dynamically updating an application, Bruce allows you to easily update configurations without manual intervention.

Chaining Workflows and Going Further

Imagine chaining multiple workflows together—triggering an agent via a webhook on a git commit, then launching another workflow based on success or failure. Bruce and Bruce make building advanced CI/CD pipelines a breeze, giving you the freedom to integrate webhooks, automate deployments, and even power machine learning pipelines.

With the power of Bruce and Bruce, the possibilities are endless. Sign up for a free Bruce account today to explore advanced features and unlock more automation potential.

Thank you for choosing Bruce!

For support or to submit issues, visit GitHub: Bruce