diff --git a/README.md b/README.md index 0fb271209..be07bbe49 100644 --- a/README.md +++ b/README.md @@ -1,108 +1,72 @@ -Antidote +AntidoteDB ============ + [![Build Status](https://travis-ci.org/AntidoteDB/antidote.svg?branch=master)](https://travis-ci.org/AntidoteDB/antidote) [![Coverage Status](https://coveralls.io/repos/github/AntidoteDB/antidote/badge.svg?branch=master)](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).