Install

Ackal's command-line tool (ackalctl) and the two proxies (ackalctl-http-proxy, ackalctl-file-proxy) are distributed as Linux containers. Using containers simplifies software delivery and increases the likelihood that the software will work on your machines.

If you are unable to use Linux containers, please Contact Us

Ackal's command-line tool (ackalctl) and the two proxies (ackalctl-http-proxy, ackalctl-file-proxy) are available here:

• ackalctl
• ackalctl-http-proxy
• ackalctl-file-proxy

The current version is: v0.0.38.

Container images are pulled if not cached locally but, if you'd prefer, you can docker pull these:

docker pull ghcr.io/brabantcourt/ackalctl:v0.0.38
docker pull ghcr.io/brabantcourt/ackalctl-file-proxy:v0.0.38
docker pull ghcr.io/brabantcourt/ackalctl-http-proxy:v0.0.38
                            

If you're running on Linux and you would prefer to run the binaries from these containers directly, you can cp the binary from a container create'd from the image:

BIN="ackalctl" # Image name == binary name
ID=$(docker create ghcr.io/brabantcourt/${BIN}:v0.0.38)
docker cp \
  ${ID}:/${BIN} \
  ${PWD}
                            

To run any of these commands, you can use the following commands:

NOTE ackalctl and ackalctl-http-proxy require credentials.json. All the containers may be configured using config.json. We recommend that you mount ${HOME}/.config/ackalctl into the container so that both files may be used.

ackalctl

CUSTOMER_ID="[YOUR CUSTOMER ID]

docker run \
--interactive --tty --rm \
--env=ACKAL_CUSTOMER_ID=${CUSTOMER_ID} \
--volume="${HOME}/.config/ackalctl:/root/.config/ackalctl" \
ghcr.io/brabantcourt/ackalctl:v0.0.38
                                

ackalctl-http-proxy

ackalctl-http-proxy publishes a port.

You can use any available host port and container port and they need not match.

CUSTOMER_ID="[YOUR CUSTOMER ID]

PORT="5000"
ENDPOINT="0.0.0.0:${PORT}"

docker run \
--interactive --rm --tty \
--env=ACKAL_CUSTOMER_ID=${CUSTOMER_ID} \
--publish="${PORT}:${PORT}" \
--volume="${HOME}/.config/ackalctl:/root/.config/ackalctl" \
ghcr.io/brabantcourt/ackalctl-http-proxy:v0.0.38 \
  --endpoint="${ENDPOINT}"
                                

ackalctl-file-proxy

ackalctl-file-proxy writes a file containing your health checks to your host.

You can choose the name and folder for this file.

CUSTOMER_ID="[YOUR CUSTOMER ID]

FILENAME="healthchecks.yml"

docker run \
--interactive --rm --tty \
--env=ACKAL_CUSTOMER_ID=${CUSTOMER_ID} \
--volume="${HOME}/.config/ackalctl:/root/.config/" \
--volume="${PWD}/${FILENAME}:/${FILENAME}:rw" \
ackalctl \
ghcr.io/brabantcourt/ackalctl-file-proxy:v0.0.38 \
--filename="/${FILENAME}" \
--period="30s"
                              

IMPORTANT In the remainder of the documentation, when you see ackalctl, ackalctl-file-proxy and ackalctl-http-proxy, you should replace these with the above container run commands.

To create a User account and subscribe to Ackal, please visit the Ackal Console.

You will need to:

1. Sign in using a Google, Microsoft or GitHub account.
2. Subscribe to Ackal using Stripe.

Once you have subscribed to Ackal:

• A Customer account will be created for you and its ID will be sent to the email account associated with your User account. You will need to provide the Customer ID when using Ackal. (see: config.json
• You should click DOWNLOAD to save your credentials.json file. This file will be used in the next step (see: credentials.json).

NOTE One Customer account (e.g. for an organization) may have multiple User accounts.

To authenticate these tools to Ackal's services, you will need to store credentials.json in your ${HOME}/.config/ackalctl folder.

{
	"jwt": "...",
	"refresh_token": "...",
	"expiration": 1643788800
}
                            

You are encouraged to create config.json in your ${HOME}/.config/ackalctl folder, replacing the value of customer.id with the Customer ID provided to you when you created your User account.

{
  "customer":{
    "id":"..."
  },
  "services":{
    "ackal":"service.ack.al:443",
    "renew":"renew.ack.al:443"
  }
}
                            

Using config.json saves repeatedly specifying this file's values on the command-line when you use ackalctl and the proxies.

ackalctl used with config.json

ackalctl \
--endpoint="server-01:443" \
--period="300s" \
--location_ids="the-dalles,tokyo" \
--services="ServiceA,ServiceB" \
create check
                            

ackalctl used without config.json

ackalctl \
--customer_id="${CUSTOMER_ID}" \
--ackal="service.ack.al:443" \
--renew="renew.ack.al:443" \
--endpoint="server-01:443" \
--period="300s" \
--location_ids="the-dalles,tokyo" \
--services="ServiceA,ServiceB" \
create check
                            

You should now be able to run ackalctl commands.

Let's start by simply listing location from which health checks may be run:

ackalctl \
list locations
                            

If the above command returned a list of locations, then your environment is correctly configured and you can begin creating checks

If the command does not work, please review the steps above to ensure that you followed them correctly.