Initial Configuration

Configuring the scheduler

Once the scheduler stack is running based on the previous step, you can test if everything went smoothly by accessing the UI at http://localhost:9002(or the port you have specified in the compose file). this will greet you with a login screen by default as you haven’t configured the target backend yet.

Setting up the database

Note : Setting up the databases is necessary for the scheduler to function properly

Back to the backend setup, the main database being used is a mysql database, that needs 2 databases to be created before running the backend.

1. The scheduler database, this will house the jobs definition and the jobs stats, the default name is scheduler_db
2. The base database, this will be used to handle authentication and any user related data, the default name is scheduler_base

Once the databases are created ( create database <dbname>; ) running the backend will check and run any schema migrations that are missing.

Setting up the backend

The TypeScheduler has a list of necessary env variables to run properly, these .env variables are set ONLY ONCE, and then they are saved into the appConfig table. These configuration become only updatable via the API or the UI.

A number of necessary variables that are needed to run the backend for the first time are :

# Mandatory Env variable
MASTER_ENCRYPTION_KEY= // this should be a base64 encoded key

# Databases
DB_HOST=mysql
DB_PORT=3306
DB_USERNAME=root
DB_PASSWORD=root
SCHEDULER_DB_NAME=scheduler_db

BASE_DB_HOST=mysql
BASE_DB_NAME=scheduler_base
BASE_DB_USERNAME=root
BASE_DB_PASSWORD=root
BASE_DB_PORT=3306

Generating the MASTER_ENCRYPTION_KEY

The MASTER_ENCRYPTION_KEY is a critical security component used to encrypt and decrypt sensitive configuration values in the database. You must generate a unique, cryptographically secure key for each deployment. Never share or reuse keys across different environments.

To generate a secure base64-encoded encryption key, use the following TypeScript code:

import crypto from "crypto"

const key = crypto.randomBytes(32).toString("base64")

This generates a 32-byte (256-bit) random key and encodes it in base64 format, which is the expected format for the MASTER_ENCRYPTION_KEY environment variable.

⚠️ Security Note: Store this key securely! Once configured, the key is essential for decrypting existing encrypted configuration values. Losing this key will result in permanent data loss for any encrypted configurations.

The provided .env file is a complete one with all the default and settable values set already but you can change them as you wish based on your needs. a more detailed explanation of each variable can be found on the backend repo

backend volumes

The backend accepts the following volumes that are used to extract data from the container to your host machine :

volumes:
  - ./my_app_source:/usr/src/app/src/jobs:ro <-- this is the main job folder, this should be the entire project with it's node_modules folder
  - ./logs:/usr/src/app/src/logs/ <-- this is the logs folder, general logs and job specific file logs (if enabled)
  - ./outputs:/usr/src/app/src/outputs/ <-- this is the job outputs folders, cache files and general files as well db backups
  - ./plugins:/usr/src/app/src/external/userPlugins <-- this is for the custom user plugins, i.e. the notification services, you cna have any number of subdivisions here the file loader won't mind

Setting up the frontend

To set the target backend hit the keyboard shortcut command + l or alt +l (depending on your OS) a sliding drawer will show and you can input the target URL, in this case it should be http://localhost:8080. here you can also save the target locally so that you can swap between multiple if you have that case. (the UI icons here are informative)

Once the target is set you can refresh the page and either login (if you are doing this a second time) or register using, don’t worry there is no email verification for now. Greeting you will be the main jobs list, a table structure that will list all your saved Tasks, a + New Job button will let you add a new task.

Setting up the external services

The external services we mean here are :

• Gotify
• Ntfy
• Loki

These are ALL OPTIONAL, and not setting their host in the .env file will disable them. Each of them need one or more configuration variables to be fully functional. A full .env.example is also available with the latest configuration values

The following are only needed for the most basic setup, all configs can be updated later :

1. for Gotify, you will need 4 variables :

• GOTIFY_URL : The host and port of your gotify server (same as the UI). Gotify is easy enough to install and a sample docker server is available in this repo.
• GOTIFY_TOKEN : The user token. I recommend creating a different user for the scheduler.
• GOTIFY_APP_TOKEN : The application token for the successful notification.
• GOTIFY_ERROR_APP_TOKEN : the application token for the error and crashes notifications.

2. For loki you will need :

• GRAFANA_LOKI_URL : The host and port of your loki server.
• GRAFANA_LOKI_USERNAME : The username for the loki server.
• GRAFANA_LOKI_PASSWORD : The password for the loki server.