## About The Project
Plombery is a simple task scheduler for Python with a web UI and a REST API,
if you need to run and monitor recurring python scripts then it's
the right tool for you!
> This project is at its beginning, so it can be shaped and improved with
> your feedback and help!
> If you like it, star it ๐! If you want a feature or find a bug, open an issue.
## Features
- โฐ Task scheduling based on [APScheduler](https://github.com/agronholm/apscheduler) (supports Interval, Cron and Date triggers)
- ๐ป Built-in Web interface, no HTML/JS/CSS coding required
- ๐ฉโ๐ป๐ Pipelines and tasks are defined in pure Python
- ๐๏ธ Pipelines can be parametrized via [Pydantic](https://docs.pydantic.dev/)
- ๐ Pipelines can be run manually from the web UI
- ๐ Secured via OAuth2
- ๐ Debug each run exploring logs and output data
- ๐ฉ Monitor the pipelines and get alerted if something goes wrong
- ๐ฃ Use the REST API for advanced integrations
When you shouldn't use it:
- you need a lot of scalability and you want to run on a distributed system
- you want a no-code tool or you don't want to use Python
## ๐ Getting Started
Check the ๐ [official website](https://lucafaggianelli.github.io/plombery/)
to get started with Plombery.
## ๐ฎ Try on GitHub Codespaces
Try Plombery with some demo pipelines on GitHub Codespaces:
Codespaces are development environments that run in the cloud so you
can run a project without cloning it, installing deps etc, here's an how
to:
- Go to the the [lucafaggianelli/plombery](https://github.com/lucafaggianelli/plombery) GitHub page
- Click on the green **Code** button on the top right
- Choose the **Codespaces** tab
- Click on *create new codespace from main* or reuse an existing one
- A new page will open at `github.dev`, wait for the environment build
- Once your codespace is ready you'll see an interface similar to VSCode
- Some commands will be run in the terminal to build the frontend etc., wait for their completion
- If everything went well, Plombery home page will be open in a new browser tab
- Changes in the Python code will be immediately reflected in the web page, like if you were developing
on your laptop
## ๐ง Show me the code
This is how it looks a minimalist pipeline:
I know you want to see it!
## ๐ฃ Roadmap
See the [open issues](https://github.com/lucafaggianelli/plombery/issues) for a full list of proposed features (and known issues).
## ๐ฉโ๐ป Contributing
Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated**.
If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement".
Don't forget to give the project a star! Thanks again!
1. Fork the Project
2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)
3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the Branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request
### Development
Clone a fork of this repo and start your dev environment.
Create a python virtual environment:
```sh
python -m venv .venv
# on Mac/Linux
source .venv/bin/activate
# on Win
.venv/Script/activate
```
and install the dependencies:
```sh
pip install ".[dev]"
```
for development purposes, it's useful to run the example application:
```sh
cd examples/
# Create a venv for the example app
python -m venv .venv
source .venv/bin/activate
pip install -r requirements
./run.sh
# or ./run.ps1 on windows
```
The React frontend is in the `frontend/` folder, enter the folder
and install the dependencies:
```sh
cd frontend/
# The project uses pnpm as dependency manager, if you don't have
# it, you must install it.
# This command will install the deps:
pnpm
```
run the development server:
```sh
pnpm dev
```
### Documentation
The documentation website is based on MkDocs Material, the source code is in the
`docs/` folder and the config is in the `mkdocs.yml` file.
To run a local dev server, run:
```
mkdocs serve
```
### Testing
Tests are based on `pytest`, to run the entire suite just run:
```sh
pytest
```
To run tests coverage, run:
```sh
coverage run -m pytest
coverage report -m
```
## License
Distributed under the MIT License. See `LICENSE.txt` for more information.
## Acknowledgments
Plombery is built on top of amazing techs:
- [FastAPI](https://fastapi.tiangolo.com/)
- [Pydantic](https://docs.pydantic.dev/)
- [APScheduler](https://apscheduler.readthedocs.io/)
- [Apprise](https://github.com/caronc/apprise)
- [React](https://react.dev/)
- [Vite](https://vitejs.dev/)
- [Tremor](https://www.tremor.so/)
