-
Notifications
You must be signed in to change notification settings - Fork 88
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Albert Schimpf
committed
Nov 13, 2019
1 parent
1281f49
commit 184d51b
Showing
1 changed file
with
47 additions
and
83 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,108 +1,72 @@ | ||
| Antidote | ||
| AntidoteDB | ||
| ============ | ||
|
|
||
| [](https://travis-ci.org/AntidoteDB/antidote) | ||
| [](https://coveralls.io/github/AntidoteDB/antidote?branch=master) | ||
|
|
||
| Welcome to the Antidote repository, the reference platform of the [SyncFree European Project](https://syncfree.lip6.fr/) and the [LightKone European Project](https://www.lightkone.eu/) | ||
|
|
||
| You will find all information in the documentation at [http://antidotedb.eu](http://antidotedb.eu). | ||
|
|
||
| For benchmarking Antidote deployments, checkout the [Antidote Benchmarks](https://github.com/AntidoteDB/Benchmarks) repository. | ||
|
|
||
| For monitoring Antidote deployments, checkout the [Antidote Stats repository](https://github.com/AntidoteDB/antidote_stats) repository. | ||
|
|
||
|
|
||
|
|
||
| Development | ||
| ----------- | ||
| Welcome to the Antidote repository, the reference platform of the [SyncFree European Project](https://syncfree.lip6.fr/) and the [LightKone European Project](https://www.lightkone.eu/). | ||
|
|
||
| Antidote requires Erlang 21 or greater. | ||
| Description | ||
| =========== | ||
|
|
||
| Use the following `Makefile` targets to build and test antidote: | ||
| AntidoteDB is a highly available geo-replicated key-value database. | ||
| AntidoteDB provides features that help programmers to write correct applications while having the same performance and horizontal scalability as AP/NoSQL databases. | ||
| Furthermore, AntidoteDB operations are based on the principle of synchronization-free execution by using Conflict-free replicated datatypes (*CRDTs*). | ||
|
|
||
| # compile the project: | ||
| make compile | ||
|
|
||
| # run the unit tests: | ||
| make test | ||
| Features | ||
| ========= | ||
|
|
||
| # run the system tests: | ||
| make systests | ||
|
|
||
| # run the release test: | ||
| make reltest | ||
| **CRDTs** | ||
|
|
||
| # run dialyzer to check types: | ||
| make dialyzer | ||
|
|
||
| # run linter | ||
| make lint | ||
| High-level replicated data types that are designed to work correctly in the presence of concurrent updates and partial failures. | ||
|
|
||
| # open a shell: | ||
| make shell | ||
| **Highly Available Transactions** | ||
|
|
||
| # build a release: | ||
| make rel | ||
|
|
||
| Using a Release | ||
| ----------- | ||
| Traditional ACID transactions were built for single-machine deployments. | ||
| On the one hand, it is expensive to implement ACID transactions in distributed deployments. | ||
| On the other hand, highly-available transactions (HAT) provide strong consistency within a data center, | ||
| but still perform well in geo-replicated deployments. | ||
|
|
||
| After building a release with `make rel`, Antidote can be started with the generated executable file. | ||
| The release executable is located at `_build/default/bin/rel/antidote/releases/bin/antidote`. | ||
| It should be started with the node name and cookie configured. | ||
| Setting the cookie is optional, setting the node name is mandatory. | ||
| **Geo-replication** | ||
|
|
||
| # start antidote with given short node name as a foreground process | ||
| NODE_NAME=testing ./antidote foreground | ||
|
|
||
| # start antidote with given long node name with an erlang interactive console attached | ||
| NODE_NAME=testing ./antidote console | ||
|
|
||
|
|
||
| Dynamic Release Configuration | ||
| ----------- | ||
| Designed to run on multiple servers in locations distributed world-wide. | ||
| It provides continuous functioning even when there are failures or network partition. | ||
|
|
||
| The release executable is dynamically configurable with OS environment variables. | ||
| The default configuration can be found in the config file folder `config`. | ||
| Only `NODE_NAME`, `COOKIE`, `ROOT_DIR_PREFIX`, `LOGGER_DIR_PREFIX` and `DATA_DIR_PREFIX` are expected to be provided via OS environment variables. | ||
| All other configuration has to be set via [erlang application environment arguments](http://erlang.org/doc/man/erl.html#flags) `-Application Par Val`, | ||
| where variable expansion can be used in the `Val` part. | ||
|
|
||
| Example: | ||
| How to Use | ||
| ========== | ||
|
|
||
| ```shell script | ||
| # start antidote with a unified directory, set logging level to warning | ||
| # assume NODE_NAME, ROOT_PREFIX_DIR (`antidote/`), P1, P2, P3, P4, and P5 OS variables | ||
| # have been exported before | ||
| # modify appliation configurations (see sys.config.src and other .config files for options) | ||
| # logging level and all ports | ||
| # disable certification checks for concurrent transactions | ||
| ./antidote foreground \ | ||
| -kernel logging_level warning \ | ||
| -riak_core handoff_port $P1 \ | ||
| -ranch pb_port $P2 \ | ||
| -antidote pubsub_port $P3 \ | ||
| -antidote logreader_port $P4 \ | ||
| -antidote_stats metrics_port $P5 \ | ||
| -antidote txn_check false | ||
| ``` | ||
| You will find all information on the [project website](http://antidotedb.eu) or the [usage documentation](https://antidotedb.gitbook.io/documentation/). | ||
|
|
||
| Code style | ||
| ----------- | ||
| Small tutorials on how to use Antidote can be found for [Java](https://github.com/AntidoteDB/antidote-java-tutorial) | ||
| and [Jupyter Notebook](https://github.com/AntidoteDB/antidote-jupyter-notebook). | ||
|
|
||
| Before commiting code run `make lint` to check the code style. | ||
| Topics: | ||
|
|
||
| In addition there are the following rules which are not checked automatically: | ||
| * [Configuring Features of Antidote]() | ||
| * [Benchmarking Antidote](https://github.com/AntidoteDB/Benchmarks) | ||
| * [Deploying Antidote]() | ||
| * [Natively]() | ||
| * [Local Docker setup]() | ||
| * [Docker Swarm]() | ||
| * [Kubernetes]() | ||
| * [Monitoring an Antidote instance or data center](https://github.com/AntidoteDB/antidote_stats) | ||
| * [Protocol Buffer API](https://antidotedb.gitbook.io/documentation/api/protocol-buffer-api) | ||
| * [Erlang Client Repository](https://github.com/AntidoteDB/antidote-erlang-client) | ||
| * [Java Client Repository](https://github.com/AntidoteDB/antidote-java-client) | ||
| * [JavaScript Client Repository](https://github.com/AntidoteDB/antidote_ts_client) | ||
| * [Go Client Repository](https://github.com/AntidoteDB/antidote-go-client) | ||
| * [Python Client Repository](https://github.com/AntidoteDB/antidote-python-client) | ||
|
|
||
| - Indentation should use 4 spaces (no tabs) | ||
| - Exported functions must be documented and have a type specification | ||
| Applications that use AntidoteDB: | ||
|
|
||
| Working on dependencies | ||
| ----------- | ||
| * [Calender App](https://github.com/AntidoteDB/calender-app) | ||
|
|
||
| When working on dependencies of Antidote it can be helpful to use them as [Checkout Dependencies](https://www.rebar3.org/docs/dependencies#section-checkout-dependencies): | ||
|
|
||
| - Create a folder named `_checkouts` in your `antidote` folder (next to the `_build` folder) | ||
| - Clone or symlink the dependency into that folder. The folder name in `_checkouts` must be the name of the dependency in `rebar.config`. | ||
| - When running a rebar3 task on Antidote, it will always use the latest version from the dependencies. It will also recompile all other dependencies, which can be avoided [by patching rebar3](https://github.com/erlang/rebar3/issues/2152) | ||
| Contributing & Development | ||
| ============== | ||
|
|
||
| Antidote encourages open-source development. | ||
| If you want to contribute, you can find all necessary information in the [developer documentation](). | ||
| To make yourself familiar with AntidoteDB, you can start by looking at [good first issues](https://github.com/AntidoteDB/antidote/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22). |