JustFlow

JustFlow is a modern workflow automation platform, combining orchestration, execution, and a web interface in a single monorepo.

Table of Contents

• Features
• Self Hosting & Setup
• Runners
• Project Structure
• Local Development
• Release Conventions
• Contributing
• License

Features

• Project Management: Organize flows, invite members, and control access.
• Flows: Design and automate workflows visually.
• Failure Pipelines: Trigger recovery or alternative flows on errors.
• Runners: Execute flows, self-hosted or shared, extensible via plugins.
• Scalability: Scale JustFlow and runners to your workload.
• Team Collaboration: Invite team members, assign roles, manage permissions.
• Audit Logs: Track changes and activities for compliance and transparency.

Self Hosting & Setup

JustFlow can be self-hosted using Docker, Docker Compose, or Helm. You can set up JustFlow using the new automated setup flow (recommended) or manually via configuration files.

Note: JustFlow requires a separately hosted PostgreSQL database. The main JustFlow image does not include a built-in database.

Docker Images

• ghcr.io/justlabv1/justflow:latest – Full version (frontend + backend)
• ghcr.io/justlabv1/justflow:vx.x.x – Versioned releases
• ghcr.io/justlabv1/justflow:frontend-latest – Frontend only
• ghcr.io/justlabv1/justflow:backend-latest – Backend only
• ghcr.io/justlabv1/justflow:runner-latest – Runner only

Setup Options

1. Automated Setup (Recommended)

After starting JustFlow, visit the /setup page in your browser. The setup wizard will guide you through configuring database, encryption, and admin user. All settings are stored securely and can be updated later in the admin area.

2. Environment Variables

You can configure JustFlow using environment variables for backend and frontend. See the documentation for all available variables.

3. Manual Configuration (Advanced)

You can still use a manual config.yaml for backend configuration. Mount your config file into the container:

docker run -p 8080:8080 -v /your/config/path/config.yaml:/etc/justflow/config.yaml ghcr.io/justlabv1/justflow:latest

Example config: apps/backend/config/config.yaml

Docker Compose

Use our docker-compose.yaml for a quick start. It includes PostgreSQL and the full JustFlow image. You can use the setup wizard or mount your own config file as described above.

Helm Chart

Deploy JustFlow with our Helm chart, which supports integrated setup and runner management. See the Helm Repo for details.

Frontend Only

To run only the frontend, provide the backend endpoint via environment variable:

docker run -p 80:3000 -e NEXT_PUBLIC_API_URL=https://api-url.com ghcr.io/justlabv1/justflow:frontend-latest

Backend Only

docker run -p 80:3000 -v /your/config/path/config.yaml:/etc/justflow/config.yaml ghcr.io/justlabv1/justflow:backend-latest

Runners

JustFlow uses the v1Flows Runner as its execution engine. At least one runner must be connected for flows to run. You can add runners via the setup wizard, project settings, or the admin runner page.

The runner source now lives in apps/runner. Built-in and maintained plugins live in runner-plugins.

Project Structure

The project structure is organized as follows:

• apps/backend: API, business logic, database, configuration
• apps/frontend: Next.js frontend
• apps/runner: Runner service and release artifacts
• runner-plugins: Action and endpoint plugins, each with its own Go module
• pkg/contracts: Shared transport types used by runner and plugins

Local Development

To develop JustFlow locally, you can use either the automated setup or manual config file:

Backend

1. Clone the repository:

   git clone git@github.com:v1Flows/JustFlow.git
   cd justflow

2. Install dependencies:

   cd apps/backend && go mod download

3. Start the backend:

   • Automated Setup:

     go run main.go

     Then visit http://localhost:8080/setup in your browser to complete the setup wizard.
   • Manual Config: Create your config.yaml (see example above) and run:

     go run main.go --config config/config.yaml

Runner

1. Navigate to the runner directory:

   cd apps/runner

2. Install dependencies:

   go mod download

3. Start the runner:

   go run ./cmd/runner --config config/config.yaml

Frontend

1. Navigate to the frontend directory:

   cd apps/frontend

2. Install dependencies:

   pnpm install

3. Create a .env.local file and add the backend API URL:

   NEXT_PUBLIC_API_URL="http://localhost:8080"

4. Start the development server:

   pnpm dev

Release Conventions

• JustFlow app releases: push tags like justflow-v1.2.3
• Runner releases: push tags like runner-v1.2.3
• Plugin releases: update a plugin .version file on main or develop
• Manual image builds: use the root Build Docker Images Manually workflow

All active CI and release workflows live in the root .github/workflows directory.

Contributing

We welcome contributions! To get started:

1. Fork the repository.
2. Create a new branch:

   git checkout -b feature/your-feature-name

3. Make your changes and commit:

   git commit -m "Add your commit message"

4. Push your branch:

   git push origin feature/your-feature-name

5. Open a pull request on GitHub.

License

This project is licensed under the GNU AFFERO GENERAL PUBLIC LICENSE Version 3. See the LICENSE for details.