# Installation

You can install Workerless in two ways:

Download and run the binary on a Linux machine.
Run the official docker image.

Once you purchase your Workerless license (opens new window), you'll find a link to download the binary and the license file in your dashboard (opens new window).

# Installing on a Server

If you choose to run Workerless on a server, you'll need to configure a processe monitoring tool like Supervisor (opens new window) to ensure Workerless is running at all times.

A simple configuration like this will work:

[program:workerless]
process_name=%(program_name)s_%(process_num)02d
command=/home/workerless --queues=high,low --function=my-function
autostart=true
autorestart=true
user=ec2-user
numprocs=1
redirect_stderr=true
stdout_logfile=/home/workerless.log

Workerless is a light weight binary that you can run on a very small server. This could be a Vapor JumpBox (opens new window) or any EC2 instance running inside your AWS account. You could run it outside AWS too if you want.

# Installing on Fargate (Serverless)

You can configure an ECS Fargate cluster to run Workerless for you without having to manage any servers. Workerless has an official Docker image that you can run inside an ECS service and configure via environment variables.

The following are the steps needed to run Workerless in an ECS cluster:

# Creating IAM Roles and Policies

You'll need to create two roles, one for the Faragte service itself and one for our Workerless task.

For the Fargate service, we need to use a policy document that allows certain events:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "ecr:GetAuthorizationToken",
                "ecr:BatchCheckLayerAvailability",
                "ecr:GetDownloadUrlForLayer",
                "ecr:BatchGetImage",
                "logs:CreateLogStream",
                "logs:PutLogEvents"
            ],
            "Resource": "*"
        }
    ]
}

For the task execution role, the policy document may look like this:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "VisualEditor0",
            "Effect": "Allow",
            "Action": "cloudwatch:PutMetricData",
            "Resource": "*"
        },
        {
            "Sid": "VisualEditor1",
            "Effect": "Allow",
            "Action": [
                "lambda:InvokeFunction",
                "sqs:ReceiveMessage"
            ],
            "Resource": [
                "arn:aws:lambda:*:<account-id>:function:*",
                "arn:aws:sqs:*:<account-id>:*"
            ]
        }
    ]
}

This document allows Workerless to receives messages from any SQS queue, invoke any lambda function, and send metrics to CloudWatch.

For this role, you'll need to provide the following trust policy:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "",
            "Effect": "Allow",
            "Principal": {
                "Service": [
                    "ecs.amazonaws.com",
                    "ecs-tasks.amazonaws.com"
                ]
            },
            "Action": "sts:AssumeRole"
        }
    ]
}

# Creating A Task Definition

Next, you'll need to create a new "Task Definition" in the ECS dashboard of the AWS console.

Fill in a name for the task (e.g. workerless—appName-environment).
In the containers section, add a single container named workerless and use themsaid/workerless:latest for the image URI.
Remove any default port mappings as Workerless doesn't use that.
In the "Environment variables" section, configure the following variables:
- WORKERLESS_LICENSE_KEY: License key. Grab it from the license.txt file you downloaded from the dashboard.
- WORKERLESS_NAME: Unique name. Can use the same name of the task definition.
- WORKERLESS_QUEUES: Comma separated list of SQS queues.
- WORKERLESS_FUNCTION: Name of the lambda function to invoke.
- Check this guide for the full list of variables.
Click "Next"
For the "App environment", choose "AWS Fargate (Serverless)".
For the "Operating system/Architecture", choose "Linux/X86_64".
For the CPU & Memory, choose a configuration that works for you. I recommend that you try with .25 vCPU and .5 GB memory first.
For the "Task role", choose the role we created in the above step.
For the "Task execution role", choose the task execution role we created in the above step.
Leave everything else as default and create the task definition.

Now we told AWS how to run a Workerless container for our application.

# Creating A Cluster

For each of our applications, we will need to create a cluster in the same VPC. So, choose "Clusters" for the AWS ECS console menu and click "Create cluster".

Fill in the cluster name (e.g. workerless—appName-environment) and choose the VPC and subnets.

Leave everything else as default and create the cluster.

# Running Tasks

After the cluster is created, click on its name in the clusters list to open the cluster editor.

Click on the "Services" tab.
Click on "Deploy".
Choose "Launch type" and leave the default "Launch type" as "FARGATE".
For the "Application type", choose "Service".
For the "Family", choose the name of the task definition we created earlier.
In the "Networking" section, configure the subnets and security group.
Disable "Public IP" as Workerless doesn't need it
Click "Deploy".

# Verifying The Setup

After the services is deployed, click on its name and browse to the "Logs" tab. You should see logs sent by Workerless to verify that it's running successfully or handle any issues.

# Logs Retention Period

AWS will create a log group for each task definition we create. By default, the logs will never expire. This could result in unnecessary charges.

To fix that:

Go to the log group by clicking on "View in CloudWatch" in the "Logs" tab of your cluster service.
Click on theLog group name in the breadcrumbs.
Click on "Actions".
Choose "Edit retention Period".

← Concept Using with Vapor →