From cd7401d50e404a961de19bec40db36fdc4d8667c Mon Sep 17 00:00:00 2001 From: exAspArk Date: Fri, 2 Feb 2024 22:26:11 -0500 Subject: [PATCH] [WUP] Update README --- Makefile | 7 ++-- README.md | 70 +++++++++++++++++++++++++++++++++++++--- devbox.json | 5 +-- devbox.lock | 20 ++++++++++++ docs/docs/open-source.md | 5 +++ docs/sidebars.ts | 1 + 6 files changed, 98 insertions(+), 10 deletions(-) create mode 100644 docs/docs/open-source.md diff --git a/Makefile b/Makefile index aebff96..3cc8e63 100644 --- a/Makefile +++ b/Makefile @@ -3,13 +3,14 @@ core-install: core-test: @devbox run "cd core && pnpm test" -worker-install: - @devbox run "cd worker && pnpm install" && \ - cd worker && \ +worker-setup: + @cd worker && \ ([ ! -d debezium-server ] && \ curl -O https://repo1.maven.org/maven2/io/debezium/debezium-server-dist/2.5.0.Final/debezium-server-dist-2.5.0.Final.tar.gz && \ tar -xvf debezium-server-dist-2.5.0.Final.tar.gz && \ rm debezium-server-dist-2.5.0.Final.tar.gz) || true +worker-install: worker-setup + @devbox run "cd worker && pnpm install" worker-up: @devbox run "cd worker && pnpm concurrently -- \"pnpm:up:*\"" diff --git a/README.md b/README.md index 6b6756e..3740de7 100644 --- a/README.md +++ b/README.md @@ -22,26 +22,86 @@ # Bemi -## Running locally +Bemi automatically tracks database changes ensuring 100% reliability and a comprehensive understanding of every change. It does it by connecting PostgreSQL's [Write-Ahead Log](https://www.postgresql.org/docs/current/wal-intro.html) (WAL) and implementing [Change Data Capture](https://en.wikipedia.org/wiki/Change_data_capture) (CDC) data pattern. Designed with simplicity and non-invasiveness in mind, Bemi operates in the background and doesn't require any alterations to your existing database tables. + +## Contents + +- [Highlights](#highlights) +- [Use cases](#use-cases) +- [Quickstart](#quickstart) +- [Architecture](#architecture) +- [Testing](#testing) +- [License](#license) + +## Highlights + +- Automatic and 100% reliable database change tracking +- High performance without affecting runtime execution +- Easy-to-use without changing table structures +- Time travel querying and ability to easily filter changes +- Optional application-specific context by using [ORM packages](https://docs.bemi.io/#supported-nodejs-orms) + +## Use cases + +There's a wide range of use cases that Bemi is built for! The tech was initially built as a compliance engineering system for fintech that supported $15B worth of assets under management, but has since been extracted into a general-purpose utility. Some use cases include: + +- **Audit Trails:** Use logs for compliance purposes or surface them to customer support and external customers. +- **Time Travel:** Retrieve historical data without implementing event sourcing. +- **Troubleshooting:** Identify the root cause of application issues. +- **Change Reversion:** Revert changes made by a user or rollback all data changes within an API request. +- **Distributed Tracing:** Track changes across distributed systems. +- **Testing:** Rollback or roll-forward to different application test states. +- **Analyzing Trends:** Gain insights into historical trends and changes for informed decision-making. + +## Quickstart + +### System dependencies + +* [Node.js](https://github.com/nodejs/node) +* [NATS server](https://github.com/nats-io/nats-server) + +You can install these system dependencies manually or use [Devbox](https://github.com/jetpack-io/devbox) which uses [Nix Packages](https://github.com/NixOS/nixpkgs) providing isolated shells without containerization. + +### Installation + +With directly installed Node.js: + +```sh +make worker-setup && cd worker && npm install +``` + +Alternatively, with Devbox: ```sh make worker-install +``` + +### Data change tracking +Set environment variables specifying PostgreSQL database connection settings: + +```sh export DB_HOST=127.0.0.1 DB_PORT=5432 DB_NAME=postgres DB_USER=postgres DB_PASSWORD=postgres -make worker-up ``` -## Testing +Run all processes with directly installed Node.js: ```sh -make core-install -make core-test +cd worker && npm concurrently -- "npm:up:*" +``` + +Alternatively, with Devbox: + +```sh +make worker-up ``` ## Architecture ![Bemi Worker Architecture](docs/static/img/worker.png) + + ## License Distributed under the terms of the [SSPL-1.0 License](/LICENSE). If you need to modify and distribute the code, please release it to contribute back to the open-source community. diff --git a/devbox.json b/devbox.json index 9abb630..d80d6cb 100644 --- a/devbox.json +++ b/devbox.json @@ -1,6 +1,7 @@ { "packages": { - "nodejs": "latest", - "nats-server": "latest" + "nodejs": "latest", + "nats-server": "latest", + "nodePackages.pnpm": "latest" } } diff --git a/devbox.lock b/devbox.lock index edff0e9..bd069ca 100644 --- a/devbox.lock +++ b/devbox.lock @@ -21,6 +21,26 @@ } } }, + "nodePackages.pnpm@latest": { + "last_modified": "2024-01-23T02:13:08Z", + "resolved": "github:NixOS/nixpkgs/4d3d04cfd372a0511f12b885c9822e406b00fe8e#nodePackages.pnpm", + "source": "devbox-search", + "version": "8.14.0", + "systems": { + "aarch64-darwin": { + "store_path": "/nix/store/rw37gcc3m93kh2hq3pi8891g41p54518-pnpm-8.14.0" + }, + "aarch64-linux": { + "store_path": "/nix/store/ab961l4fcs1n5ldfy4463kqr4pln1cxc-pnpm-8.14.0" + }, + "x86_64-darwin": { + "store_path": "/nix/store/06qmz8k1gi9s68mcynlyis35w2pj6fl6-pnpm-8.14.0" + }, + "x86_64-linux": { + "store_path": "/nix/store/pgzxiapcydn1mmqh1w4jkl9pcw7ybbj4-pnpm-8.14.0" + } + } + }, "nodejs@latest": { "last_modified": "2023-11-19T17:46:56Z", "resolved": "github:NixOS/nixpkgs/0bf3f5cf6a98b5d077cdcdb00a6d4b3d92bc78b5#nodejs_21", diff --git a/docs/docs/open-source.md b/docs/docs/open-source.md new file mode 100644 index 0000000..c7662f6 --- /dev/null +++ b/docs/docs/open-source.md @@ -0,0 +1,5 @@ +# Open Source + +BemiHQ/bemi +
+
diff --git a/docs/sidebars.ts b/docs/sidebars.ts index 8dd9462..00182c8 100644 --- a/docs/sidebars.ts +++ b/docs/sidebars.ts @@ -31,6 +31,7 @@ const sidebars: SidebarsConfig = { 'orms/typeorm', ], }, + 'open-source', ], };