Metadata-Version: 2.4
Name: snakemake-logger-plugin-flowo
Version: 1.0.2
Summary: A unified PostgreSQL-based logging plugin and backend for Snakemake
Author-email: Haomiao Zhang <zhanghm@iregene.com>, Jingmin Zhang <zhangjm@iregene.com>
License: MIT
License-File: LICENSE
Requires-Python: >=3.12
Requires-Dist: httpx>=0.28.1
Requires-Dist: pydantic-settings>=2.9.1
Requires-Dist: pydantic>=2.11.5
Requires-Dist: snakemake
Requires-Dist: snakemake-interface-logger-plugins
Requires-Dist: sqlalchemy>=2.0.41
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5.0; extra == 'docs'
Requires-Dist: mkdocs>=1.6.0; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.25.0; extra == 'docs'
Provides-Extra: server
Requires-Dist: alembic>=1.16.1; extra == 'server'
Requires-Dist: anytree>=2.13.0; extra == 'server'
Requires-Dist: asyncpg>=0.30.0; extra == 'server'
Requires-Dist: fastapi-users[sqlalchemy]>=15.0.3; extra == 'server'
Requires-Dist: fastapi[standard]>=0.115.12; extra == 'server'
Requires-Dist: passlib[bcrypt]>=1.7.4; extra == 'server'
Requires-Dist: psutil>=7.0.0; extra == 'server'
Requires-Dist: psycopg2-binary>=2.9.9; extra == 'server'
Requires-Dist: sse-starlette>=3.1.2; extra == 'server'
Description-Content-Type: text/markdown

# Flowo 🚀

Welcome to **Flowo** – your real-time Snakemake workflow dashboard!

Unleash the power of automation and monitoring with a fresh, interactive experience.

**Demo page: [flowo online](https://zhanghaomiao.github.io/flowo)**
**Documentation: [flowo-docs](https://flowo-docs.pages.dev/)**

---

## 📰 News

**Latest Release**: Flowo now supports user authentication and login! Additionally, we've simplified the configuration process, making it even easier to get started with workflow monitoring and management.

---

## ✨ Features

- ⚡ **Real-time Monitoring:**
  Flowo leverages Server-Sent Events (SSE) and PostgreSQL's LISTEN/NOTIFY mechanism for instant workflow updates. The frontend refreshes automatically – just sit back and watch the magic happen!

- 🚀 **Efficient Data Fetching:**
  With smart polling (every 5 seconds) and debouncing, Flowo keeps your data up-to-date without overloading the network. Fast, efficient, and always fresh.

- 🔍 **Search & Filtering:**
  Instantly find workflows by name, tags, or user. Delete workflows from the database with a click (no worries, your files are safe).

- 🧩 **Rule-based Filtering:**
  Focus on specific rules to filter jobs and update the execution timeline. Debug and optimize like a pro!

- 🖼️ **Result Preview:**
  Instantly preview output files generated by your favorite rules, right in the Results submenu. No more hunting for results!

- 📋 **Logging System:**
  Dive into detailed workflow and job logs. Analyze, learn, and improve your processes with ease.

---

### 🛠️ Workflows

![Workflow](docs/assets/images/workflow.png)

### 📊 Dashboard

![Dashboard](docs/assets/images/dashboard.png)

### 🕹️ Jobs

| ![DAG](docs/assets/images/dag.png) | ![Jobs](docs/assets/images/jobs.png) |
| ---------------------------------- | ------------------------------------ |

---

## 🚦 Installation

- **Requirements:**
  - 🐧 Linux system
  - 🐳 Docker
  - 🐍 snakemake

---

### 1️⃣ Install the Snakemake Logger Plugin

Now let’s install [snakemake-logger-plugin-flowo](https://pypi.org/project/snakemake-logger-plugin-flowo/), a logging plugin for Snakemake. Once the installation is complete, simply add `--logger flowo` to your Snakemake command, and the execution status of your workflow will be automatically sent to the Flowo web server for real-time monitoring and visualization.

```sh
pip install snakemake-logger-plugin-flowo
```

### 2️⃣ Install the Flowo web server

```sh
git clone https://github.com/zhanghaomiao/flowo.git
cd flowo
cp env.example .env
```

Edit your `.env` file as follows. In most cases, you only need to modify `FLOWO_WORKING_PATH` to point to the directory where you run your Snakemake workflows. If you don’t need to view Snakefiles, log files, result previews, etc. in the Flowo web interface — and only want to monitor workflow, job, and rule execution status — there is no need to configure these additional paths.

```sh
# Application Settings
DOMAIN=localhost
PORT=3100
TZ=Asia/Shanghai

# Database Configuration
POSTGRES_DB=flowo_logs
POSTGRES_USER=flowo
POSTGRES_PASSWORD=flowo_password
POSTGRES_HOST=localhost
BACKEND_CORS_ORIGINS=["*"]

# Workflow Directory
FLOWO_WORKING_PATH=/path/to/flowo_project_dir  #Important: set this to your workflow directory
```

Start the Flowo web service:

```sh
docker compose up -d
```

![login](docs/assets/images/login.png)
Open [http://localhost:3100](http://localhost:3100) in your browser. Create your account and log in. If you see the Flowo interface and the "Live Updates" icon is green, congratulations—your Flowo web service is running successfully!

![token](docs/assets/images/token.png)
Next, create a token, which is required to configure the snakemake-logger-plugin-flowo. Click the user icon in the top-right corner, select Generate New Token, then provide a name and set an expiration time. Once confirmed, the token will be generated successfully.

![cli](docs/assets/images/cli.png)
After that, click Config to access a CLI snippet. Copy and run this command in the terminal where snakemake-logger-plugin-flowo is installed. Once it finishes executing, the setup will be complete.

---

## 🚀 Usage

All set!
Let's test with a demo project:

```sh
cd /path/to/flowo_project_dir
mkdir demo                # Create a demo project folder
cd demo
wget https://raw.githubusercontent.com/zhanghaomiao/flowo/refs/heads/main/tests/demos/Snakefile
# Run snakemake with flowo logger
snakemake \
    --logger flowo \
    --logger-flowo-name=your_project_name \
    --logger-flowo-tags="tagA,tagB,tagC"
```

Now, check out your workflow in the Flowo web! Good luck! 🎉

## Developer Guide

### 📦 Docker Environments

We provide two ways to run Flowo using Docker:

1. **Production Mode (`docker-compose.yml`)**:
   Uses pre-built images from GitHub Container Registry (GHCR). Ideal for deployment.

   ```sh
   docker compose pull
   docker compose up -d
   ```

2. **Development Mode (`docker-compose.dev.yml`)**:
   Builds images from your local source code. Ideal for testing changes.
   ```sh
   docker compose -f docker-compose.dev.yml up --build
   ```

### 🏷️ Versioning & Releases

Versioning is handled automatically through GitHub Actions.

#### Automating Version Bumps

To increment the project version:

1. Go to the **Actions** tab in your GitHub repository.
2. Select the **"Bump Version"** workflow.
3. Click **"Run workflow"**, choose the bump type (`patch`, `minor`, or `major`), and run.
4. This will update `pyproject.toml` and commit the change automatically.

#### Creating Releases

Whenever you push to the `release` branch, a new GitHub Release is created, and Docker images are pushed to GHCR with the version tag.

---
