About
Synapse is a vendor-neutral, free, open-source, and community-driven Workflow Management System (WFMS) implementing the Serverless Workflow specification.
Requirements
- .NET 6 or later
Optionally, and depending on which flavor of the Synapse Server you chose to run, you might require:
Quick start
1. Download and extract synctl:
On Windows:
wget https://github.com/serverlessworkflow/synapse/releases/latest/download/synctl-win-x64.zip
tar -xf synctl-win-x64.zip
On Linux:
wget https://github.com/serverlessworkflow/synapse/releases/latest/download/synctl-linux-x64.tar.gz
tar -xf synctl-linux-x64.tar.gz
On Mac OSX:
wget https://github.com/serverlessworkflow/synapse/releases/latest/download/synctl-osx-x64.tar.gz
tar -xf synctl-osx-x64.tar.gz
2. Install Synapse:
Natively:
synctl system install native
On Docker:
synctl system install docker
On Kubernetes:
synctl system install kubernetes
3. Have fun!
Server
Installing
Native
The Synapse Server can run natively on Windows, Mac and Linux, without any dependencies aside from .NET. Even though it is the easier way to get started, it should only be used for tests purposes. For production, you should prefer the Docker or Kubernetes based setups.
To get started, just download the appropriate release for your system, then start it using the following command:
dotnet run ./Synapse.Server.dllFor more information on how to configure a Native Synapse Server, please read the docs.
Docker
Docker is the recommended way to run the Synapse Server for those who do not want to host it on a Kubernetes cluster.
To run the server on Docker, simply execute the following command in your system's shell:
docker run --name synapse -v /var/run/docker.sock:/var/run/docker.sock -p 42286:42286 -p 41387:41387 ghcr.io/serverlessworkflow/synapse:latestNotes: you need to mount the docker.sock and/or run the container with the --network host option for Synapse to be able to spawn its own containers
For more information on how to configure Synapse for Docker, please read the docs.
Docker-Compose
Docker-Compose helps you to get started easier and faster than with Docker, as it allows to declare and configure multiple container at once, which will likely be needed if using persistence, for instance.
To run the server on Docker-Compose, simply execute the following command in your system's shell:
docker-compose -f deployment/docker-compose/docker-compose.yml up -dAlternatively, you can use the file using EventStore and MongoDB powered persistence:
docker-compose -f deployment/docker-compose/eventstore+mongo.yml up -dKubernetes
Kubernetes is the preferred way to run the Synapse Server, as it offers a wide range of tools to configure, run and manage multiple containers at once, which will likely be needed if using persistence, for instance.
To run the server on Kubernetes, simply execute the following command in your system's shell:
kubectl apply -f deployment/kubernetes/stand-alone.yamlAlternatively, you can use the file using EventStore and MongoDB powered persistence:
kubectl apply -f deployment/kubernetes/eventstore+mongo.yamlUser Interfaces
Synapse provides 2 different UIs for interacting with the server:
GUI
To get started, simply open a web browser and navigate to the Synapse Server's base url.
For more information on how to use the Dashboard, please read the docs.
CLI
synctl is a Command Line Interface (CLI) used to interact with the Synapse Server.
To get started, just download the appropriate release for your system, then type the following command:
synctl --helpFor more information on how to use synctl, please read the docs.
Application Programing Interfaces
The Synapse Server is shipped with 3 different APIs, each addressing a different use-case. All the implementations of those APIs are supplied with their respective client library.
Management API
The Synapse Management API is used to manage workflows and their instances.
Implementations:
Monitoring API
The Synapse Monitoring API is used for real-time observability of workflows and their instances. It is used by the Dashboard to enable real-time updates.
Implementations:
Runtime API
The Synapse Runtime API is used by workers to run workflows and maintain their state. It preferably should not be used by anything else than runtime executors.
Implementations:
Community
We have a growing community working together to build a community-driven and vendor-neutral workflow ecosystem. Community contributions are welcome and much needed to foster project growth.
See here for the list of community members that have contributed to the specification.
To learn how to contribute to the specification reference the 'how to contribute' doc.
If you have any copyright questions when contributing to a CNCF project like this one, reference the Ownership of Copyrights in CNCF Project Contributions doc.
Code of Conduct
As contributors and maintainers of this project, and in the interest of fostering an open and welcoming community, we pledge to respect all people who contribute through reporting issues, posting feature requests, updating documentation, submitting pull requests or patches, and other activities.
We are committed to making participation in this project a harassment-free experience for everyone, regardless of level of experience, gender, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, ethnicity, age, religion, or nationality.
See our full project Code of Conduct information here.
Repository Structure
Here is the outline of the repository to help navigate the specification documents:
| File/Directory | Description |
|---|---|
| LICENSE | Specification License doc |
| OWNERS | Defines the current maintainers and approvers |
| MAINTAINERS | Project Maintainers Info |
| GOVERNANCE | Project Governance Info |
| CONTRIBUTING | Documentation on how to contribute to the project |
| CODE-OF-CONDUCT | Defines the project's Code of Conduct |
| ROADMAP | Project Roadmap |