diff --git a/README.md b/README.md index 8b53cafc..613ccc24 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,8 @@ # πŸ€– Zrb (Read: Zaruba) : A Super Framework for Your Super App -![](https://raw.githubusercontent.com/state-alchemists/zrb/main/images/zrb/android-chrome-192x192.png) +![](https://raw.githubusercontent.com/state-alchemists/zrb/main/_images/zrb/android-chrome-192x192.png) -[πŸ“– Documentation](https://github.com/state-alchemists/zrb/blob/main/docs/README.md) | [🏁 Getting Started](https://github.com/state-alchemists/zrb/blob/main/docs/getting-started.md) | [πŸ’ƒ Oops, I did it Again](https://github.com/state-alchemists/zrb/blob/main/docs/oops-i-did-it-again/README.md)| [❓ FAQ](https://github.com/state-alchemists/zrb/blob/main/docs/faq/README.md) +[πŸ“– Documentation](https://github.com/state-alchemists/zrb/blob/main/docs/README.md) | [🏁 Getting Started](https://github.com/state-alchemists/zrb/blob/main/docs/getting-started.md) | [πŸ’ƒ Oops, I did it Again](https://github.com/state-alchemists/zrb/blob/main/docs/oops-i-did-it-again/README.md) | [❓ FAQ](https://github.com/state-alchemists/zrb/blob/main/docs/faq/README.md) Zrb is a [CLI-based](https://en.wikipedia.org/wiki/Command-line_interface) automation [tool](https://en.wikipedia.org/wiki/Programming_tool) and [low-code](https://en.wikipedia.org/wiki/Low-code_development_platform) platform. Once installed, Zrb will help you automate day-to-day tasks, generate projects and applications, and even deploy your applications to Kubernetes with a few commands. @@ -39,9 +39,9 @@ zrb project start-fastapp --fastapp-run-mode "monolith" You will be able to access the application by pointing your browser to [http://localhost:3000](http://localhost:3000) -![](https://raw.githubusercontent.com/state-alchemists/zrb/main/images/fastapp.png) +![](https://raw.githubusercontent.com/state-alchemists/zrb/main/_images/fastapp.png) -Furthermore, you can also run the same application as `microservices`, run the application as `docker containers`, and even doing some deployments into your `kubernetes cluster`. +Furthermore, you can run the same application as `microservices`, run the application as `docker containers`, and even do some deployments into your `kubernetes cluster`. ```bash @@ -62,7 +62,7 @@ You can visit [our tutorials](https://github.com/state-alchemists/zrb/blob/main/ ## Zrb as a task-automation framework -Aside from the builtin capabilities, Zrb also allows you to define your automation commands in Python. To do so, you need to create/modify a file named `zrb_init.py`. +Aside from the built-in capabilities, Zrb also allows you to define your automation commands in Python. To do so, you must create/modify a file named `zrb_init.py`. ```python # filename: zrb_init.py @@ -111,7 +111,7 @@ Installing Zrb in your system is as easy as typing the following command in your pip install zrb ``` -Just like any other Python package, you can also install Zrb in your [virtual environment](https://docs.python.org/3/library/venv.html). This will allow you to have many versions of Zrb on the same computer. +Like any other Python package, you can install Zrb in your [virtual environment](https://docs.python.org/3/library/venv.html). This will allow you to have many versions of Zrb on the same computer. > ⚠️ If the command doesn't work, you probably don't have Pip/Python on your computer. See `Main prerequisites` subsection to install them. @@ -183,7 +183,7 @@ If you prefer Python distribution like [conda](https://docs.conda.io/en/latest/) If you want to generate applications using Zrb and run them on your computer, you will also need: -- 🐸 `Node.Js` and `Npm`. +- 🐸 `Node.Js` and `Npm`. - You need Node.Js to modify/transpile frontend code into static files. - You can visit the [Node.Js website](https://nodejs.org/en) for installation instructions. - πŸ‹ `Docker` and `Docker-compose` plugin. @@ -200,7 +200,7 @@ If you want to generate applications using Zrb and run them on your computer, yo # 🏁 Getting started -We have a nice [getting started guide](https://github.com/state-alchemists/zrb/blob/main/docs/getting-started.md) to help you cover the basics. Make sure to check it outπŸ˜‰. +We have an excellent [getting started guide](https://github.com/state-alchemists/zrb/blob/main/docs/getting-started.md) to help you cover the basics. Make sure to check it outπŸ˜‰. # πŸ“– Documentation @@ -210,10 +210,10 @@ You can visit [Zrb documentation](https://github.com/state-alchemists/zrb/blob/m Help Red Skull to click the donation button: -[![](https://raw.githubusercontent.com/state-alchemists/zrb/main/images/donator.png)](https://stalchmst.com/donation) +[![](https://raw.githubusercontent.com/state-alchemists/zrb/main/_images/donator.png)](https://stalchmst.com/donation) # πŸŽ‰ Fun fact > Madou Ring Zaruba (ι­”ε°ŽθΌͺアルバ, Madōrin Zaruba) is a Madougu which supports bearers of the Garo Armor. [(Garo Wiki | Fandom)](https://garo.fandom.com/wiki/Zaruba) -![Madou Ring Zaruba on Kouga's Hand](https://raw.githubusercontent.com/state-alchemists/zrb/main/images/madou-ring-zaruba.jpg) +![Madou Ring Zaruba on Kouga's Hand](https://raw.githubusercontent.com/state-alchemists/zrb/main/_images/madou-ring-zaruba.jpg) diff --git a/images/donator.png b/_images/donator.png similarity index 100% rename from images/donator.png rename to _images/donator.png diff --git a/images/fastapp.png b/_images/fastapp.png similarity index 100% rename from images/fastapp.png rename to _images/fastapp.png diff --git a/images/fastapp/about.txt b/_images/fastapp/about.txt similarity index 100% rename from images/fastapp/about.txt rename to _images/fastapp/about.txt diff --git a/images/fastapp/android-chrome-192x192.png b/_images/fastapp/android-chrome-192x192.png similarity index 100% rename from images/fastapp/android-chrome-192x192.png rename to _images/fastapp/android-chrome-192x192.png diff --git a/images/fastapp/android-chrome-512x512.png b/_images/fastapp/android-chrome-512x512.png similarity index 100% rename from images/fastapp/android-chrome-512x512.png rename to _images/fastapp/android-chrome-512x512.png diff --git a/images/fastapp/apple-touch-icon.png b/_images/fastapp/apple-touch-icon.png similarity index 100% rename from images/fastapp/apple-touch-icon.png rename to _images/fastapp/apple-touch-icon.png diff --git a/images/fastapp/favicon-16x16.png b/_images/fastapp/favicon-16x16.png similarity index 100% rename from images/fastapp/favicon-16x16.png rename to _images/fastapp/favicon-16x16.png diff --git a/images/fastapp/favicon-32x32.png b/_images/fastapp/favicon-32x32.png similarity index 100% rename from images/fastapp/favicon-32x32.png rename to _images/fastapp/favicon-32x32.png diff --git a/images/fastapp/favicon.ico b/_images/fastapp/favicon.ico similarity index 100% rename from images/fastapp/favicon.ico rename to _images/fastapp/favicon.ico diff --git a/images/fastapp/site.webmanifest b/_images/fastapp/site.webmanifest similarity index 100% rename from images/fastapp/site.webmanifest rename to _images/fastapp/site.webmanifest diff --git a/images/madou-ring-zaruba.jpg b/_images/madou-ring-zaruba.jpg similarity index 100% rename from images/madou-ring-zaruba.jpg rename to _images/madou-ring-zaruba.jpg diff --git a/images/zrb/about.txt b/_images/zrb/about.txt similarity index 100% rename from images/zrb/about.txt rename to _images/zrb/about.txt diff --git a/images/zrb/android-chrome-192x192.png b/_images/zrb/android-chrome-192x192.png similarity index 100% rename from images/zrb/android-chrome-192x192.png rename to _images/zrb/android-chrome-192x192.png diff --git a/images/zrb/android-chrome-512x512.png b/_images/zrb/android-chrome-512x512.png similarity index 100% rename from images/zrb/android-chrome-512x512.png rename to _images/zrb/android-chrome-512x512.png diff --git a/images/zrb/apple-touch-icon.png b/_images/zrb/apple-touch-icon.png similarity index 100% rename from images/zrb/apple-touch-icon.png rename to _images/zrb/apple-touch-icon.png diff --git a/images/zrb/favicon-16x16.png b/_images/zrb/favicon-16x16.png similarity index 100% rename from images/zrb/favicon-16x16.png rename to _images/zrb/favicon-16x16.png diff --git a/images/zrb/favicon-32x32.png b/_images/zrb/favicon-32x32.png similarity index 100% rename from images/zrb/favicon-32x32.png rename to _images/zrb/favicon-32x32.png diff --git a/images/zrb/favicon.ico b/_images/zrb/favicon.ico similarity index 100% rename from images/zrb/favicon.ico rename to _images/zrb/favicon.ico diff --git a/images/zrb/site.webmanifest b/_images/zrb/site.webmanifest similarity index 100% rename from images/zrb/site.webmanifest rename to _images/zrb/site.webmanifest diff --git a/docs/faq/do-zrb-has-a-scheduler.md b/docs/faq/do-zrb-has-a-scheduler.md new file mode 100644 index 00000000..2625cd0b --- /dev/null +++ b/docs/faq/do-zrb-has-a-scheduler.md @@ -0,0 +1,11 @@ +πŸ”– [Table of Contents](../README.md) / [FAQ](README.md) + +# Do Zrb has a Scheduler? + +No. Zrb focus is to help you run complicated tasks in a single run. You will need third party alternatives to make your tasks run by schedule. + +# What can I do to make a scheduled task? + +Don't worry, there are some [tricks](../tutorials/run-task-by-schedule.md) you can use + +πŸ”– [Table of Contents](../README.md) / [FAQ](README.md) diff --git a/docs/getting-started.md b/docs/getting-started.md index e1370424..5557b12d 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -4,7 +4,9 @@ Zrb is an automation tool. With Zrb you can run tasks using command-line-interface. -There are project tasks and common tasks. Project tasks are usually bind to a project, while common tasks can be executed from anywhere. +You can also define Zrb tasks using Python. + +This getting-started guide covers all the basic you need to know before working with Zrb. # Running a task diff --git a/docs/oops-i-did-it-again/README.md b/docs/oops-i-did-it-again/README.md index 18d71fa5..3c935194 100644 --- a/docs/oops-i-did-it-again/README.md +++ b/docs/oops-i-did-it-again/README.md @@ -2,9 +2,9 @@ # Oops, I Did It Again: Most Common Mistakes When Working with Zrb -Collection of common mistakes when working with Zrb +Collection of the most common mistakes when working with Zrb -- [Defining Different Tasks with The Same Name](defining-different-tasks-with-the-same-name.md) +- [Defining Different Tasks With The Same Name](defining-different-tasks-with-the-same-name.md) πŸ”– [Table of Contents](../README.md) / [Oops, I Did It Again](README.md) \ No newline at end of file diff --git a/docs/oops-i-did-it-again/defining-different-tasks-with-the-same-name.md b/docs/oops-i-did-it-again/defining-different-tasks-with-the-same-name.md index 061dfe2f..5c11f159 100644 --- a/docs/oops-i-did-it-again/defining-different-tasks-with-the-same-name.md +++ b/docs/oops-i-did-it-again/defining-different-tasks-with-the-same-name.md @@ -1,6 +1,6 @@ πŸ”– [Table of Contents](../README.md) / [Oops, I Did It Again](README.md) -# Defining Different Tasks with The Same Name +# Defining Different Tasks With The Same Name ```python from zrb import CmdTask, runner @@ -20,8 +20,15 @@ runner.register(hello2) You can see that `hello1` and `hello2` share the same name. Thus, `hello2` will override `hello1` -This leads to so many problems. +This leads to tricky situation. For example, you believe that `zrb hello` should yield `hello mars`, yet it keep showing `hello world`. + +# Detecting the Problem + +First of all, detecting the problem will be easier if you use the same convention to define task property: +- Use single quote instead of double quote for string value whenever possible +- Not using space between property name and property value (i.e., `name='hello'`) + +Once you do so, you can use `search` feature in your IDE/text editor (e.g., `name='hello'`). Make sure every task name is unique. -For example, you believe that `zrb hello` should yield `hello mars`, yet it keep showing `hello world`. πŸ”– [Table of Contents](../README.md) / [Oops, I Did It Again](README.md) diff --git a/docs/tutorials/README.md b/docs/tutorials/README.md index 970bd0e9..62055bfb 100644 --- a/docs/tutorials/README.md +++ b/docs/tutorials/README.md @@ -2,11 +2,12 @@ # Tutorials -- [Preparing your machine for development](preparing-your-machine-for-development.md) -- [Development to deployment: Low code](development-to-deployment-low-code.md) -- [Run task programmatically](run-task-programmatically.md) -- [Define task dynamically](define-task-dynamically.md) -- [Copy task](copy-task.md) +- [Preparing Your Machine for Development](preparing-your-machine-for-development.md) +- [Development to Deployment: Low Code](development-to-deployment-low-code.md) +- [Run Task programmatically](run-task-programmatically.md) +- [Run Task by Schedule](run-task-by-schedule.md) +- [Define Task Dynamically](define-task-dynamically.md) +- [Copy and Re-use task](copy-and-reuse-task.md) - [Extending CmdTask: Sending Message to Slack](extending-cmd-task.md) πŸ”– [Table of Contents](../README.md) diff --git a/docs/tutorials/images/enable-kubernetes-on-docker-desktop.png b/docs/tutorials/_images/enable-kubernetes-on-docker-desktop.png similarity index 100% rename from docs/tutorials/images/enable-kubernetes-on-docker-desktop.png rename to docs/tutorials/_images/enable-kubernetes-on-docker-desktop.png diff --git a/docs/tutorials/images/enable-wsl-integration.png b/docs/tutorials/_images/enable-wsl-integration.png similarity index 100% rename from docs/tutorials/images/enable-wsl-integration.png rename to docs/tutorials/_images/enable-wsl-integration.png diff --git a/docs/tutorials/images/my-app-list-of-book.png b/docs/tutorials/_images/my-app-list-of-book.png similarity index 100% rename from docs/tutorials/images/my-app-list-of-book.png rename to docs/tutorials/_images/my-app-list-of-book.png diff --git a/docs/tutorials/copy-task.md b/docs/tutorials/copy-and-reuse-task.md similarity index 97% rename from docs/tutorials/copy-task.md rename to docs/tutorials/copy-and-reuse-task.md index 6a28861a..f50c1032 100644 --- a/docs/tutorials/copy-task.md +++ b/docs/tutorials/copy-and-reuse-task.md @@ -1,6 +1,6 @@ πŸ”– [Table of Contents](../README.md) / [Tutorials](README.md) -# Copy task +# Copy and Re-use Task Rather than define similar task twice, you can copy existing task into a new one and applying necessary changes. diff --git a/docs/tutorials/define-task-dynamically.md b/docs/tutorials/define-task-dynamically.md index 8f7a19a5..1bdbd91e 100644 --- a/docs/tutorials/define-task-dynamically.md +++ b/docs/tutorials/define-task-dynamically.md @@ -1,6 +1,6 @@ πŸ”– [Table of Contents](../README.md) / [Tutorials](README.md) -# Define task dynamically +# Define Task Dynamically Every task definition in Zrb are written in Python. diff --git a/docs/tutorials/development-to-deployment-low-code.md b/docs/tutorials/development-to-deployment-low-code.md index c9fda942..c15bec81 100644 --- a/docs/tutorials/development-to-deployment-low-code.md +++ b/docs/tutorials/development-to-deployment-low-code.md @@ -72,7 +72,7 @@ The default username and password will be `root` and `toor`. Try to add some books. -![](images/my-app-list-of-book.png) +![](_images/my-app-list-of-book.png) # Override default username and password @@ -187,7 +187,7 @@ Make sure to also run `zrb project stop-myapp-container` to prevent your contain For this demo, we are using docker desktop with kubernetes enabled. -![](images/enable-kubernetes-on-docker-desktop.png) +![](_images/enable-kubernetes-on-docker-desktop.png) Once your kubernetes cluster is running, you can invoke the following command: diff --git a/docs/tutorials/preparing-your-machine-for-development.md b/docs/tutorials/preparing-your-machine-for-development.md index e44dd017..94a4a7b3 100644 --- a/docs/tutorials/preparing-your-machine-for-development.md +++ b/docs/tutorials/preparing-your-machine-for-development.md @@ -1,6 +1,6 @@ πŸ”– [Table of Contents](../README.md) / [Tutorials](README.md) -# Preparing your machine +# Preparing Your Machine > This guide has been tested under `debian 12` and `ubuntu 22.0.4` @@ -14,7 +14,7 @@ Zrb is a Python package. So, in order to get started, you will need to have: sudo apt install python-is-python3 python3-dev python3-distutils python3-openssl python3-pip python3-venv ``` -# Creating venv for setup +# Creating Venv for Setup Once you have install Python, pip, and venv, you can make a directory named `zrb-setup` and create a virtual environment. @@ -30,7 +30,7 @@ Please note that whenever you want to work with the virtual environment, you wil Creating different virtual environment for each of your projects make your pip packages more manageable. For example, you will be able to have two different version of the same python package in the different project. -# Install zrb on venv +# Install Zrb on Venv After having your virtual environment set up, you can install `zrb` on your virtual environment: @@ -38,7 +38,7 @@ After having your virtual environment set up, you can install `zrb` on your virt pip install zrb ``` -# Install essential packages for ubuntu/debian +# Install Essential Packages for Ubuntu/Debian Next you can install essential packages for development. @@ -46,7 +46,7 @@ Next you can install essential packages for development. zrb ubuntu install packages ``` -# Setup zsh +# Setup Zsh Zsh and oh-my-zsh is highly compatible, yet provide the same experience as `bash`. Installing zsh is not mandatory, but highly recommended. @@ -79,7 +79,7 @@ To install tmux, you need to invoke the following command: zrb devtool install tmux ``` -# Setup pyenv +# Setup Pyenv With pyenv, you can manage multiple python environments. Installing pyenv is highly recommended. @@ -90,7 +90,7 @@ You can install pyenv by invoking the following command: zrb devtool install pyenv ``` -# Setup nvm +# Setup Nvm Nvm allows you to manage multiple node.js environments. Node.js is mandatory if you want to run `fastapp` application. @@ -100,11 +100,11 @@ You can install nvm by invoking the following command: zrb devtool install nvm ``` -# Setup docker and kubectl +# Setup Docker and Kubectl If you are using WSL, the most recommended way is by installing docker desktop and enable wsl-integration -![Enable WSL integration](./images/enable-wsl-integration.png) +![Enable WSL integration](_images/enable-wsl-integration.png) Otherwise, you can invoke the following command: @@ -113,7 +113,7 @@ zrb devtool install docker zrb devtool install kubectl ``` -# Setup pulumi +# Setup Pulumi To setup pulumi, you can invoke the following command: @@ -123,7 +123,7 @@ zrb devtool install pulumi You need pulumi for app deployment. -# Setup other tools +# Setup Other Tools There are some other tools you might need to install depending on your needs. For example: diff --git a/docs/tutorials/run-task-by-schedule.md b/docs/tutorials/run-task-by-schedule.md new file mode 100644 index 00000000..b836f711 --- /dev/null +++ b/docs/tutorials/run-task-by-schedule.md @@ -0,0 +1,86 @@ +πŸ”– [Table of Contents](../README.md) / [Tutorials](README.md) + +# Run Task by Schedule + +Zrb doesn't have any built-in scheduler. However, there are some workarounds you can use: + +- Creating an infinite loop +- Using Cronjob +- Using Airflow or other orchestrator + +# Creating an Infinite Loop + +The simplest approach is by turning your task into a function, and call your function after some interval. + +For example, you want to run `hello` task every 5 seconds. Then you can create the following Python script and run it. + +```python +# file: scheduled_hello.py +from zrb import CmdTask, runner + +import time + +# You can import `hello` task from somewhere else +# e.g., from zrb_init import hello +hello = CmdTask( + name='hello', + cmd='echo "hello world"' +) +runner.register(hello) + +while True: + time.sleep(5) + fn = hello.to_function() + hello() +``` + +```bash +python scheduled_hello.py +``` + +# Using CronJob + + +A cron job is usually formatted as follow: + +``` +minute hour day month weekday +``` + +Suppose you want to run `zrb hello` every 5 seconds, you can edit your crontab by executing: + +```bash +crontab -e +``` + +Crontab will ask you to choose a text editor. You can choose `nano` or anything you are familiar with. + +Once you have choose your text editor, you can add the following line: + +``` +5 * * * * zrb hello >> .hello.log 2>&1 +``` + +# Using Airflow or Other Orchestrator + +If you are using Airflow, you can use a [BashOperator](https://airflow.apache.org/docs/apache-airflow/stable/howto/operator/bash.html) as follow: + +```python +from airflow.decorators import dag +from airflow.operators.bash import BashOperator +from pendulum import datetime + + +@dag(start_date=datetime(2022, 8, 1), schedule='@daily', catchup=False) +def hello_dag(): + run_hello = BashOperator( + task_id="run_hello", + bash_command="zrb hello", + ) +``` + +For other orchestrators, please visit their respective document. As long as there is a way to run a python function or running a CLI command, you will be able to run Zrb Task + + + +πŸ”– [Table of Contents](../README.md) / [Tutorials](README.md)