diff --git a/articles/enterprise/components/api-overview.md b/articles/enterprise/components/api-overview.md index f3d4a7e..ddef664 100644 --- a/articles/enterprise/components/api-overview.md +++ b/articles/enterprise/components/api-overview.md @@ -212,7 +212,7 @@ following error when attempting to register: ### RPM Package -The Stoplight API configuration file is located at the location: +The Stoplight API configuration file is located at the path: ```bash /etc/stoplight-api/stoplight-api.cfg diff --git a/articles/enterprise/components/tasker-overview.md b/articles/enterprise/components/tasker-overview.md index a6eb063..8fa70f2 100644 --- a/articles/enterprise/components/tasker-overview.md +++ b/articles/enterprise/components/tasker-overview.md @@ -1,4 +1,4 @@ -# Stoplight Tasker +# Tasker The **Tasker** component runs scheduled and on-demand tasks for the Stoplight platform. @@ -10,15 +10,40 @@ The **Tasker** component runs scheduled and on-demand tasks for the Stoplight pl > > Tasker requires a Redis instance to be available when starting. Be sure to setup Redis before installing Tasker. +> #### Networking Details +> +> The default port for the Tasker component is TCP port **9432**. This port can +> be customzied via configuration variable. +> +> Tasker must be able to receive incoming connections from the following components: +> +> * API +> +> Tasker must be able to make outgoing connections to the following components: +> +> * API +> * Redis + +> #### Component Dependencies +> +> Make sure the following components are available **before** starting the Tasker +> service: +> +> * Redis + ## Installation Tasker can be installed with Docker or via RPM package. ### RPM Package -Prior to installing the RPM package, you will need to have the Stoplight package repository installed and configured with your user-specific credentials. +Prior to installing the RPM package, you will need to have the Stoplight package +repository installed and configured with your user-specific credentials. -You can do this by copying-and-pasting the contents below into a terminal: +#### Setting up the Package Repository + +You can setup the Stoplight package repo by copying-and-pasting the contents +below into a terminal: ```bash # expose credentials to environment first @@ -39,13 +64,15 @@ EOF > Be sure to set your repository credentials before issuing the `cat` command +#### Installing the Tasker Package + Once the repository is configured properly, you can install the Tasker component using the command: ```bash sudo yum install tasker -y ``` -### Docker Installation +### Docker To install the Tasker component with Docker, run the command below: @@ -53,15 +80,84 @@ To install the Tasker component with Docker, run the command below: docker pull quay.io/stoplight/tasker ``` -> Note, if you have not already authenticated with the Stoplight container registry, you will be prompted for credentials +> Note, if you have not already authenticated with the Stoplight container +> registry, you will be prompted for credentials. -## Configuring and Running +## Configuration -To configure the Tasker component, you will need to provide runtime settings and connection details for a running Redis instance. +To configure the Tasker component, you will need to provide runtime settings and +connection details for a running Redis instance. -### Package-based Installations +### Variables -#### Configuring the Service +#### TASKER_HTTP_BIND + +The `TASKER_HTTP_BIND` variable is the bind address and port used for serving +the Tasker HTTP API. + +``` +TASKER_HTTP_BIND="localhost:9432" +``` + +#### TASKER_MODE + +The `TASKER_MODE` variable is the operation mode that Tasker should use when +executing jobs. Valid values for `TASKER_MODE` are `docker` and `shell`. + +``` +TASKER_MODE="shell" +``` + +> If not specified, Tasker defaults to using `docker` mode. + +#### CORE_ROOT + +The `CORE_ROOT` denotes the absolutel path to stoplight-hub-builder package root. + +``` +CORE_ROOT="/opt/stoplight-hub-builder" +``` + +> This variable is only required when running in `shell` mode. + +#### TASKER_REDIS_HOSTPORT + +The `TASKER_REDIS_HOSTPORT` variable denotes the Redis instance host:port to connect to. + +``` +TASKER_REDIS_HOSTPORT="redis://redis:6379" +``` + +> Redis must be available before starting service. + +#### TASKER_REDIS_PASSWORD + +The `TASKER_REDIS_PASSWORD` variable is an optional password to use when +connecting to the Redis instance. + +``` +TASKER_REDIS_PASSWORD="" +``` + +#### TASKER_REDIS_DATABASE + +The `TASKER_REDIS_DATABASE` variable is the Redis database used by Tasker for +storing job state. + +``` +TASKER_REDIS_DATABASE="0" +``` + +#### TASKER_REDIS_NAMESPACE + +The `TASKER_REDIS_NAMESPACE` variable is the Redis namespace used by Tasker for +storing job state. + +``` +TASKER_REDIS_NAMESPACE="tasker" +``` + +### RPM Package The Tasker configuration is located at: @@ -69,69 +165,16 @@ The Tasker configuration is located at: /etc/tasker/tasker.cfg ``` -The above file should contain the following entries: +Be sure to customize any variables as needed to match your environment before +starting the Tasker service. -```bash -# Tasker HTTP bind address (host:port) -TASKER_HTTP_BIND="localhost:9432" +> Any changes to the Tasker configuration require a service restart in order to +> take effect. -# Tasker execution mode, either 'shell' or 'docker' -TASKER_MODE="shell" -# If using 'shell' mode, provide path to stoplight-hub-builder package root -CORE_ROOT="/opt/stoplight-hub-builder" +### Docker -# Redis host:port to connect to (must be available before starting service) -TASKER_REDIS_HOSTPORT="redis://redis:6379" -# Redis password, if any -TASKER_REDIS_PASSWORD="" -# Redis database -TASKER_REDIS_DATABASE="0" -# Redis namespace -TASKER_REDIS_NAMESPACE="" -``` - -Be sure to customize any of the variables above as needed. - -#### Starting the Service - -To start the Tasker server, run the command: - -```bash -sudo systemctl start tasker -``` - -Once started, you can see the status of the service using the command: - -```bash -sudo systemctl status tasker -``` - -### Docker Installations - -#### Configuring the Container - -The Tasker container can be configured via the following environment variables: - -```bash -# Tasker HTTP bind address (host:port) -TASKER_HTTP_BIND="localhost:9432" - -# Tasker execution mode, either 'shell' or 'docker' -TASKER_MODE="shell" -# If using 'shell' mode, provide path to stoplight-hub-builder package root -CORE_ROOT="/opt/stoplight-hub-builder" - -# Redis host:port to connect to (must be available before starting service) -TASKER_REDIS_HOSTPORT="redis://redis:6379" -# Redis password, if any -TASKER_REDIS_PASSWORD="" -# Redis database -TASKER_REDIS_DATABASE="0" -# Redis namespace -TASKER_REDIS_NAMESPACE="" -``` - -To expose these to the Docker runtime, either write them to a file and use the `--env-file` argument: +To expose these to the Docker runtime, either write them to a file and use the +`--env-file` argument: ```bash cat <tasker-env-vars @@ -148,27 +191,47 @@ Alternatively, you can expose them one at a time with the `-e` flag: docker run -e TASKER_HTTP_BIND=0.0.0.0:9432 ... ``` -#### Starting the Container +## Running + +### RPM Package + +To start the Tasker server, run the command: + +```bash +sudo systemctl start tasker +``` + +Once started, you can see the status of the service using the command: + +```bash +sudo systemctl status tasker +``` + +### Docker To start the Tasker container, use the command: ```bash docker run \ - --restart on-failure \ - --env-file tasker-env-vars \ - -p 9432:9432 \ - quay.io/stoplight/tasker:latest + --restart on-failure \ + --env-file tasker-env-vars \ + -p 9432:9432 \ + quay.io/stoplight/tasker:latest ``` -If started properly, the container should be marked with a healthy status after 30 seconds. Use the `docker ps` command to verify the container was started and is running properly. +If started properly, the container should be marked with a healthy status after +30 seconds. Use the `docker ps` command to verify the container was started and +is running properly. ## Post-install Validations -Once the Tasker component is running, you can verify the installation was successful issuing an HTTP GET request to the `/health` endpoint: +Once the Tasker component is running, you can verify the installation was +successful issuing an `HTTP GET` request to the `/health` endpoint: ```bash -# be sure to update the port here to match the installation port +# remember to update the scheme, host, and port here to match your installation curl -v http://localhost:9432/health ``` -If Tasker was installed and configured properly, you will receive an HTTP 200 reponse back. +If Tasker was installed and configured properly, you will receive an `HTTP 200` +reponse back.