Dispatch a job with a Docker Self-Hosted RUnner

User Role: Administrator, Operator, Editor

Sometimes users need to secure where jobs are created and executed behind a firewall. Dispatching a job with a self-hosted runner allows you to create jobs locally on your internal file system, run it at a later time, and even run multiple jobs simultaneously in batches. 

We recommend using Docker to manage your self-hosted runner because it implements the same container for all hosts, whether you are running on Linux, MacOS, or Windows. This method ensures that Liquibase delivers database changes seamlessly and that no conflicts with host configurations occur. It also shields the host from security issues, interacting only with the Docker container and not the host.

Prerequisites

• Generate a Personal Access Token with Operator, Editor, or Administrator privileges

• Obtain the instance subdomain

  • Example: yourcompany from https://yourcompany.liquibase.io 

Step-by-step

Download Liquibase IO CLI

1. Download the Liquibase IO CLI.

2. Extract the executable to a path of your choice. It can run from inside a directory or the system path.

3. Locate the instance subdomain.

   • Example: yourcompany from https://yourcompany.liquibase.io 

4. Obtain a Personal Access Token (PAT) with Editor, Operator, or Administrator privileges by following this guide.

5. The initial run of any CLI command will prompt you to enter the subdomain and PAT which will be saved to your configuration file, liquibase-io-config.yaml.

Install the Liquibase IO Runner

The Liquibase IO Runner consists of a JRE and Liquibase jar files. 

1. If you are using a Docker container, navigate to the CLI and run the command: lbio runner install --runtime docker
   OR

2. If you are using a local file system, navigate to the CLI and run the command: lbio runner install
   A status will appear that states: Runner installed

3. To ensure your installation is complete, run the command: lbio runner check
A status will appear that says: Runner installation is complete.

Test a local Connection

Local connections must initially be tested through the CLI. Once the connection is created in the Web GUI, the CLI can test it from the location where jobs will run.

Prerequisites

1. If a connection does not exist, see instructions to Create a Database Connection 

Step-by-step

1. From the CLI, locate your database's connection ID by running the command: lbio connection ls 

2. You will see a list of all databases you can connect to. Find the connection ID on the left; we will use 204 in this example.
   Type the test command: lbio connection test 204

This message will appear in the CLI when the connection is successful:
Liquibase command 'connect' was executed successfully.

4. Navigate back to the CLI and run lbio workflow run 101 --dispatch to run the job.

5. Optional: You can create jobs and then dispatch them at a later time. This allows you to create several separate jobs and then dispatch them all at once if some jobs are dependent of other jobs.
1. To create the job from the CLI, run lbio workflow run 101
The Job UUID will appear. Once at this stage, the Job will be Pending on the Jobs page until you dispatch or cancel this job. This is because the AWS runner will not pick up this job; it is waiting for the local Liquibase IO Runner to pick it up.
2. Run the lbio job dispatch <job-uuid> command to run an individual job.
Or run lbio job dispatch --all to dispatch all pending jobs.

The job is dispatched successfully.