Getting Started

SignalFire is designed to be easy to set up and use. To get started, follow these steps:

Setup Organization

Before using SignalFire, you must setup an organization account. Currently, SignalFire is in closed beta to obtain access please contact sales to get started. Each user must register for a SignalFire account and be added to the organization. Follow these steps to add users to an organization:

1. Navigate to your organization by clicking Organizations in the menu.
2. Click your desired organization to add users to.
3. Click Manage Members to manage organization membership.
4. Click Invite Member to invite a new member.
5. Type in the desired email address.
6. Select the desired access for the new member.
   • Admin - can request and approve signals
   • Basic - can request signals
7. The user will then receive an email to join the organization, once they accept it they will be a member of the organization.

Create Repository

Repositories are collections of Actions, that is linked to a specific git repository. This hierarchy helps organize your scripts. To create a repository:

1. Navigate to your organization by clicking Organizations in the menu.
2. Click your desired organization to add users to.
3. Click Code Actions to see your script repositories.
4. Click Add Repository to add a new repository.
5. Fill in the desired information...
   • The Git Address is the remote Git URL which can be obtained using the SignalFire CLI with sf get remote or with Git CLI using git config --get remote.origin.url.

Create Action

An Action refers to a predefined form or configuration that specifies how a particular script should be executed. To create an Action:

1. Navigate to your organization by clicking Organizations in the menu.
2. Click your desired organization to add users to.
3. Click Code Actions to see your script repositories.
4. Click your desired repository to add the Action to.
5. Click Add Action.
6. Fill in the desired information and click Add Action.
7. Set form schema, see an example. See Form Schema for more details about how the form schema works.
8. Set command logic. The command logic you create should generate a string that is a command to execute a script within side the root directory of the specified repository. See an example. See Command Logic for more details about how the command logic works. Hint: use the example form on the page to test out your command logic
9. Once you have completed setup of the Action click Update Action.

Example Form Schema

{
    "type": "object",
    "properties": {
        "name": {
            "type": "string",
            "minLength": 3,
            "maxLength": 12
        },
        "birth_year": {
            "type": "string",
            "minimum": 1000
        },
        "gender": {
            "type": "string",
            "enum": [
                "Male",
                "Female"
            ]
        },
        "email": {
            "type": "string",
            "format": "email"
        }
    },
    "required": [
        "name",
        "birth_year"
    ]
}

Learn more about Form Schema

Example Command Logic

if (form.gender != "Male" && form.gender != "Female") throw new Error("Gender is missing");
let age = new Date().getFullYear() - form.birth_year;
if (age < 18) {
  return `py ./scripts/add-child.py ${form.name} --sex ${(form.gender == "Male") ? "M" : "F"} --email "${form.email}"`
} else {
  return `py ./scripts/add-adult.py ${form.name} --sex ${(form.gender == "Male") ? "M" : "F"} --email "${form.email}"`
}

Learn more about Command Logic

Install SignalFire CLI

The SignalFire CLI is used to run scripts on the machine of your preference. You can install SignalFire CLI on Linux, Windows, and MacOS. See SignalFire CLI Installation for instruction on installation. To learn more about the SignalFire CLI commands see SignalFire CLI Commands.

Generate Machine Secret

A Machine is a computer that runs your actions. For the machine to interface with SignalFire you must generate a unique machineID and secret.

1. Navigate to your organization by clicking Organizations in the menu.
2. Click your desired organization to add users to.
3. Click Edit Organization to modify your organization.
4. Click Manage Machines to manage the organization's machines.
5. Click New Machine to add a new machine.
6. Type the desired name and description of the machine.
7. Copy the MachineID and Secret. Note: You will be unable to access the secret again.

note

You may not use the same machine token on two different machines. Once one token has used a secret it can not be used by any other machine.

Authorize SignalFire CLI

After generating a MachineID and Secret you can authorize your desired machine. To do this, access the terminal of the desired machine with SignalFire CLI installed on it. Need to install SignalFire CLI?

Add the machine token with sf token add [machineID] and then you will be prompted for the secret. Paste the secret that was provided in the previous step.

You can verify your token has been accepted with sf token ls.

Learn more about CLI Commands

Initialize Repository

Setting up a repository on your desired machine is super easy. Just access the terminal of the desired machine with SignalFire CLI installed on it and do the following:

1. Navigate to the Git Repository directory.
2. Link the repository with sf init.
3. Verify the repository has been added with sf ls.

note

You must have a repository on SignalFire with the same Git remote repository and your must have a token for that organzation on the machine you are initializing.

Generate User Certificate

A user certificate is used to sign Signals once an admin has approved them. Each certificate is assocated to a specific user, repository, and machine. Generating the certificate will happen on the machine you would like the certificate to be assocatiated with. See security for more information. Follow the following steps in the terminal on you desired machine:

1. Navigate to the Git Repository directory, you would like to generate a certificate for.
2. Generate a certificate with sf user add [email].
3. Verify the user was added with sf user ls.
4. Share this certificate with the user in a secured form and have them store it in a secure place.

Signals

A Signal is a request to execute a specific Action. You can request and approve a Signal with the following steps:

Signal Request

1. Click Dashboard to view a list of all Actions you have access to.
2. Click the desired Action you would like to request.
3. Click New Signal to request a new Signal.
4. Fill in the desired information.
5. Click Request Signal to finalize the request.
6. Wait for approval.

Signal Approval

1. Click Activity to view your and other requested Signals.
2. Click the desired Action.
3. Click Approve to approve the Signal.
4. Paste the certificate assocated with the machine and repository.
5. Signal Ready to Go!

Executing Signal Requests

After a Signal has been approved the machine must run the sf run command, learn more about CLI commands. This command will execute all pending Signals that have been approved for the machine.

We recommend setting up a Cron task on the machine to run the SignalFire execution command every couple minutes. Learn how to setup Cron Task?