:trumpet: Overview

Automatically control your docker containers up/down behavior based on a simple config file.

:question: Motivation

My main motivation for building this tool was to reduce my time spent on setting up infra related containers on my machine or in my hobby/VPS projects.

:dart: Features

   ✔️ type safe api methods by using zod validation;    ✔️ supports configs for Dockerfile, complete docker-compose or a single service of it;    ✔️ two ways to specify time-configuration for each container: per weekday or global (everyday);    ✔️ allows logs exporting to track which and when actions were done;    ✔️ three modes to overriding time specs: on (always on), of (always off) and auto (follows the time_specs);    ✔️ all customizable by specifying custom options;

:warning: Requirements

In order to use this project in your computer, you need to have the following items:

• npm: To install the package. Npm is installed alongside nodejs;
• nodejs: To actually run the package.

:bulb: Usage

To use it from the registry, first install the npm package:

# Install the package
npm install container_scheduler -g

Create a container configs file such as this (which follows this schema):

{
  "options": {
    "timezone": "America/Belem",
  },
  "containers": {
    "docker_composes": [
      {
        "name": "develop",
        "mode": "auto",
        "path": "/home/lucasvtiradentes/repos/github/projects/lifetracer_setup/env/develop/docker-compose.yml",
        "time_specs": [
          ["mon", "auto", "07:00", "23:00"],
          ["tue", "auto", "07:00", "23:00"],
          ["wed", "auto", "07:00", "23:00"],
          ["thu", "auto", "07:00", "23:00"],
          ["fri", "auto", "07:00", "23:00"],
          ["sat", "auto", "07:00", "23:00"],
          ["sun", "auto", "07:00", "23:00"]
        ]
      },
      {
        "name": "alfa",
        "mode": "off",
        "path": "/home/lucasvtiradentes/repos/github/projects/lifetracer_setup/env/alfa/docker-compose.yml",
        "time_specs": ["06:30", "23:59"]
      }
    ],
    "docker_compose_services": [
      {
        "name": "devops",
        "mode": "off",
        "path": "/home/lucasvtiradentes/repos/github/projects/lifetracer_setup/devops/docker-compose.yml",
        "time_specs": ["06:30", "23:07"],

        "service_name": "traefik"
      }
    ],
    "docker_files": [
      {
        "name": "pdv365",
        "mode": "off",
        "path": "/home/lucasvtiradentes/Desktop/repos/uds/pdv365/Dockerfile.prod",
        "time_specs": ["06:30", "12:00"],

        "mount_path": "/home/lucasvtiradentes/Desktop/repos/uds/pdv365",
        "image_name": "pdv_franqueadora_front_dev_image",
        "container_name": "pdv_franqueadora_front_dev_container",
        "options": "-d -p 3100:3100 -v \"$(pwd):/app\" -v /app/node_modules",
      }
    ]
  }
}

After that you can simply setup the cronjob to run every five minutes (if not changed by the options):

container_scheduler -s "/home/lucasvtiradentes/Desktop/configs.json"
# cs -s "/home/lucasvtiradentes/Desktop/configs.json"  <-- works as well

# tip: make sure to specify the absolute path, do not use $USER/Desktop or ~/Desktop

And thats it! now the program will run every five minutes and perform the necessary actions (up/down containers).

Notice that you can specify some options according to your needs.

To see further usage, check out the provided example.

Available configs options

{
  "timezone": "UTC",
  "string_divider": " | ",
  "empty_column_symbol": "-",
  "parse_boolean_values_to_emojis": false,
  "debug_mode": false,
  "loop_mode_check_interval_minutes": 5,
  "log_file": "",
  "log_file_maximum_lines": 10
}

Notice that the aboce options are the default options. Also, if you want to enable the log feature, you need to specify a path for the log file (on the log_file option), the file don't need to exist.

Available CLI options

Usage: container_scheduler [options]

📅 container scheduler package with minimum configuration.

Options:
  -V, --version          output the version number
  -s, --setup <file>     setup the cronjob to run the checking every x minutes
  -r, --remove           remove the cronjob to run the checking
  -c, --checking [file]  checking mode
  -l, --logs             show available logs
  -h, --help             display help for command

Advanced usage

Lets take an compose-item provided on the above configs file example:

{
  "name": "develop",
  "mode": "auto",
  "path": "/home/lucasvtiradentes/repos/github/projects/lifetracer_setup/env/develop/docker-compose.yml",
  "time_specs": [
    ["mon", "on",   "07:00", "23:00"],
    ["tue", "off",  "07:00", "23:00"],
    ["wed", "auto", "07:00", "23:00"],
    ["thu", "auto", "07:00", "23:00"],
    ["fri", "auto", "07:00", "23:00"],
    ["sat", "auto", "07:00", "23:00"],
    ["sun", "auto", "07:00", "23:00"]
  ]
}

this docker-compose item will:

• on monday run all day long (because the daily_mode is set to on)
• on tuesday will not run (because the daily_mode is set to off)
• on the rest of the days will run between "07:00" and "23:00" (because the daily_mode is set to auto)

also it is important to note this:

• the daily settings is only taking into account because the mode is set to auto
• if the mode is set to off, the compose will be down everytime
• if the mode is set to on, the compose will be up everytime

:wrench: Development

Development setup

To setup this project in your computer, download it in this link or run the following commands:

# Clone this repository
$ git clone https://github.com/lucasvtiradentes/container_scheduler

# Go into the repository
$ cd container_scheduler

After download it, go to the project folder and run these commands:

# Install dependencies using npm
$ npm install

# Run the typescript code in development mode
$ npm run dev

If you want to contribute to the project, after you make the necessary changes, run these commands to check if everything is working fine:

# Compile the code into javascript
$ npm run build

# Run the compiled code in production mode
$ npm run start

Used technologies

This project uses the following thechnologies:

:books: About

License

This project is distributed under the terms of the MIT License Version 2.0. A complete version of the license is available in the LICENSE file in this repository. Any contribution made to this project will be licensed under the MIT License Version 2.0.