Skip to content

Latest commit

 

History

History
239 lines (154 loc) · 6.96 KB

README.md

File metadata and controls

239 lines (154 loc) · 6.96 KB
Raw

SwellRT Build Status Gitter

SwellRT is an open source backend-as-a-service. It provides out-of-the-box features for apps:

  • Real-time storage (NoSQL)
  • User management
  • Authentication
  • Event based integration

SwellRT's goal is to ease development of real-time collaborative applications, specially those requiring collaborative text editing.

SwellRT objects can be shared and mutated in real-time. All changes are persisted and propagated transparently. Object state is eventually consistent.

Check out API basics:

service.open({

	id: '<object-id>'

}).then(object => {

 	// Anyone can open the object
	object.setPublic(true);

});

Set and get a property:

object.set('person', 
  { 
	name: 'Alice',
	city: 'New York'
  });
  
object.get('person.city');

Listen for updates (local or remote):

object.node('person').addListener( event => {
	
	console.log('Property Updated ');

});

Client libraries for Web and Java/Android (experimental) are provided.

Documentation and examples

API documentation can be found here

Basic examples can be found here. Try them running a SwellRT server and visiting http://localhost:9898

Running a SwellRT Server

You can build the server yourself or use our pre-built Docker image.

Building SwellRT from source code

Prerequisites

Clone the project

git clone [email protected]:P2Pvalue/swellrt.git
cd swellrt

Build

./gradlew compileJava devWeb

If you get a "User limit of inotify watches reached" error, please increase this limit following stesp here

Start the server

./gradlew run

Visit "http://localhost:9898" to check server installation and try some demos.

Docker

Get docker image of SwellRT (latest version by default). Check out all available SwellRT versions at Docker Hub:

$ docker pull p2pvalue/swellrt

Run docker container in deattached mode (-d).

$ docker run \ 
-e MONGODB_HOST=<host> \
-e MONGODB_PORT=<port> \
-e MONGODB_DB=<db name> \
-p 9898:9898 \
-h swellrt \
--name swellrt \
-d p2pvalue/swellrt

This commands also binds default SwellRT server port 9898, to port 9898 in the host machine (-p 9898:9898). Sets hostname to "swellrt" (-h). And configures SwellRT to use a MongoDB server instance with the provided parameters.

See following section to configure a MongoDB instance.

Persistent folders

For productive installations of SwellRT, config and data folders should be outside the container. For example, to put all log files in host's folder /var/log/swellrt, run docker with -v parameter:

$ docker run -v /usr/local/swellrt/log:/var/log/swellrt  -p 9898:9898 -h swellrt -d p2pvalue/swellrt

These are all the folders you can map outside the container:

Folder (Docker cointainer) Description
/usr/local/swellrt/config Server config files
/usr/local/swellrt/log Server log files
/usr/local/swellrt/sessions Persistent HTTP Sessions
/usr/local/swellrt/avatars Users avatar images
/usr/local/swellrt/attachments User files

Server config

Server configuration can be adjusted by editing files in the config/ folder. Default settings can be found in the repo.

If you map the config/ folder in your host machine, you must copy those files to it.

Post installation

Visit "http://localhost:9898" and "http://localhost:9898/chat" to check server installation and try some demos.

MongoDB

This section explains how to install and configure a MongoDB server with SwellRT.

Get latest MongoDB Docker image

$ docker pull mongo

Run mongo container

$ docker run -p 27017:27017 --name mongo -d mongo

Run SwellRT (it assumes Docker containers are using default bridge network)

$ docker run \
-e MONGODB_HOST=172.17.0.1 \
-e MONGODB_PORT=27017 \
-e MONGODB_DB=swellrt \
-p 9898:9898 \
-h swellrt \
--name swellrt \
-d p2pvalue/swellrt

The database swellrt is created automatically if it doesn't exist.

Java/Android client

An experimental Java library is in package org.swellrt.beta.client.platform.java Check out chat demo app in *org.swellrt.beta.client.platform.java.ChatDemo".

Federation

SwellRT servers can be federated using XMPP and Matrix.org protocol. Sorry, we are still writting the configuration guide. Please contact us for furhter information.

Contact and Support

Visit our Gitter Channel or email to [email protected].

Contributing

Read our contributing guide to learn more about our development process, how to propose bugfixes and improvements, and how to build and test your changes to SwellRT.

Acknowledgments

The SwellRT project is a fork of Apache Wave. Initial work of SwellRT has been funded by the EU research project P2Pvalue and supported by GRASIA research group of the Universidad Complutense of Madrid.

Cryptographic Software Notice

This distribution includes cryptographic software. The country in which you currently reside may have restrictions on the import, possession, use, and/or re-export to another country, of encryption software. BEFORE using any encryption software, please check your country's laws, regulations and policies concerning the import, possession, or use, and re-export of encryption software, to see if this is permitted. See http://www.wassenaar.org/ for more information.

The U.S. Government Department of Commerce, Bureau of Industry and Security (BIS), has classified this software as Export Commodity Control Number (ECCN) 5D002.C.1, which includes information security software using or performing cryptographic functions with asymmetric algorithms. The form and manner of this Apache Software Foundation distribution makes it eligible for export under the License Exception ENC Technology Software Unrestricted (TSU) exception (see the BIS Export Administration Regulations, Section 740.13) for both object code and source code.

The following provides more details on the included cryptographic software:

Wave requires the BouncyCastle Java cryptography APIs: http://www.bouncycastle.org/java.html