Installation #

Downloading a single binary is all it takes to get started. With the SetOps command-line interface (CLI), you can configure your app environment, deploy, and monitor your app.

Downloading the CLI #

MacOS Homebrew (recommended)

Install the setops-cli package:

brew install setopsco/manager/setops-cli

Run setops. You’re ready to go!

MacOS

Go to the Releases page on GitHub.
The most recent release is on the top. Under Assets, download the CLI at setops-cli_vX.Y.Z_darwin_amd64.bz2.
Uncompress the downloaded binary: bunzip2 setops-cli_vX.Y.Z_darwin_amd64.bz2
Mark it as executable: chmod +x setops-cli_vX.Y.Z_darwin_amd64

Move the binary to some folder in your $PATH, e.g.:

mv setops-cli_vX.Y.Z_darwin_amd64 /usr/local/bin/setops

Run setops.

In case macOS warns you about an unsigned binary, click Cancel. Open System Preferences, go to Security & Privacy, and select the General tab. There will be a button to allow running setops at the bottom of the preference pane.

You’re ready to go!
(Optional) Install Shell Completions:

Run setops completion and follow the instructions.

Linux

Go to the Releases page on GitHub.
The most recent release is on the top. Under Assets, download the CLI at setops-cli_vX.Y.Z_linux_amd64.bz2.
Uncompress the downloaded binary: bunzip2 setops-cli_vX.Y.Z_linux_amd64.bz2
Mark it as executable: chmod +x setops-cli_vX.Y.Z_linux_amd64

Move the binary to some folder in your $PATH, e.g.:

mv setops-cli_vX.Y.Z_darwin_amd64 /usr/local/bin/setops

Create a bin directory in your home directory, in which we will late place a Docker credentials helper to authenticate against the SetOps registry: mkdir -p "$HOME/bin
Add the bin directory to your PATH env variable permanently. It depends on the shell you are using how to do this, but for bash you can execute echo 'export "PATH=$HOME/bin:$PATH"' >> "$HOME/.bashrc", for zsh run echo 'export "PATH=$HOME/bin:$PATH"' >> "$HOME/.zshrc". If you use a different shell please consult its documentation on how to modify environment variables globally.
Run setops.

You’re ready to go!
(Optional) Install Shell Completions:

Run setops completion and follow the instructions.

Configure Syntax Highlighting for Visual Studio Code #

When editing SetOps stage definitions you can configure Visual Studio Code to check your definition agains the official SetOps JSON Schema. This allows for autocomplete and validation.

Install Red Hats YAML extension
Go to your user setting in json view

Add the following code snippet to configure the schema for all files ending with .setops.yaml

...
"yaml.schemas": {
    "https://api.setops.co/schema/latest/stage.setops.json": "*.setops.yaml"
},
...

If you are new to SetOps you need to be invited to a SetOps Organization by another user. Follow the invitation email’s instructions to set a password for your account. You then have access to the resources you have been invited to.

Log In #

To log into your account, run:

$ setops login

SetOps will open a browser window where you can provide your credentials. If a browser window cannot be opened, SetOps will print the link to your terminal, so you can copy it to a browser window. After successful authorization, SetOps will obtain a short living access token and a refresh token for your local CLI and store it in ~/.setops.yml alongside the provided org.

It will also attempt to configure your docker installation to be able to authenticate and push to the SetOps registry. It places a helper script docker-credential-setops in your PATH and registers it in your Docker configuration at ~/.docker/config.json. You can skip the setup using the --no-setup flag with the login command. If the automatic setup fails, you can perform a Manual Setup.

You are now ready to use the SetOps CLI.

The interactive login via a browser will not work when running the setops login command in a non-interactive environment, like a CI job. In this case, you can call setops login --service-user and pass in a username and password. However, this should only be used if it is really required since username and password are directly passed into the CLI. For better security, only an access token is stored in ~/.setops.yml, which means you need to log in again after 4 hours when the access token expires. Login via --service-user flag does not support social providers such as GitHub or Google. We recommend creating a dedicated service user account used exclusively in these scenarios.

Switch Organizations #

Suppose you are a member of multiple organizations, you can switch between them with setops organization:switch <ORGANIZATION> after successful login.

Logout #

If you want to log out from SetOps, you can do so by running setops logout. This will deauthorize the current session in your terminal. Please note that your browser will stay logged in, so you will not have to provide your credentials if you want to log in again. To also log out from the browser (e.g., to switch accounts), use setops logout --browser.

Manual Setup #

To authenticate with the SetOps registry and push images, Docker needs to be configured. SetOps uses a credential-helper, a small script that handles the authentication for Docker. The script must be placed in your PATH and registered in your Docker configuration. These steps should be performed automatically during login. If the automatic setup fails, you can place and register the Docker credential-helper manually:

Make sure Docker is installed by running docker --version from your terminal
Create a file named docker-credential-setops in a directory that is in your PATH
Copy the following script to the file and save it
```
#!/bin/bash

setops docker $@
```
The script forwards Docker’s request for credentials to the SetOps CLI.
Make the file executable e.g. by running chmod a+x /path/to/file/docker-credential-setops
Test the script by running docker-credential-setops get from your terminal
Open ~/.docker/config.json
Add the following key to the configuration and save the file
```
"credHelpers": {
   "api.setops.co": "setops"
}
```

You are now ready to use SetOps with Docker.

Going further #

Read more about the concepts which power SetOps.