Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/jaywink/social-relay

Public post relay for the Diaspora federated social network protocol
https://github.com/jaywink/social-relay

diaspora federation relay social-networks

Last synced: 26 days ago
JSON representation

Public post relay for the Diaspora federated social network protocol

Awesome Lists containing this project

README 

        
[![Build Status](https://travis-ci.org/jaywink/social-relay.svg?branch=master)](https://travis-ci.org/jaywink/social-relay) [![codecov](https://codecov.io/gh/jaywink/social-relay/branch/master/graph/badge.svg)](https://codecov.io/gh/jaywink/social-relay) [![Requirements Status](https://requires.io/github/jaywink/social-relay/requirements.svg?branch=master)](https://requires.io/github/jaywink/social-relay/requirements/?branch=master) 



[![issue tracker](https://img.shields.io/badge/issue%20tracker-gitlab-orange.svg)](https://git.feneas.org/jaywink/social-relay)



# Social-Relay



Application to act as a relay for public posts using the Diaspora protocol. Keeps track of nodes and their subscription preferences, receives payloads and forwards the payloads to subscribers. The aim is to pass public posts around in an efficient way so any new node in the network can quickly subscribe to lots of public activity, without having to wait a long time to create social relationships.



## How does one integrate to the relay system? How do I write my own relay?



See [relay design concept](https://git.feneas.org/jaywink/social-relay/blob/master/docs/relays.md).



Original idea for the relay system can be found in the [diaspora* project wiki](https://wiki.diasporafoundation.org/Relay_servers_for_public_posts).



## Installation

       

### System libraries



Depending on your database, you will probably need extra libraries installed.



For databases, PostgreSQL and MySQL/MariaDB are supported, choose one.



#### Python



Python 3.4+ is required.



#### Redis



    # Debian / Ubuntu

    sudo apt-get install redis-server



#### PostgreSQL



    # Debian / Ubuntu

    sudo apt-get install libpq-dev postgresql

    

#### MySQL/MariaDB



    # Debian / Ubuntu

    sudo apt-get install python3-dev libmysqlclient-dev 



    # Red Hat / CentOS

    sudo yum install python3-devel mysql-devel

    

#### Federation



The `federation` dependency `lxml` requires certain libraries present:

 

    # Debian / Ubuntu

    sudo apt-get install libxml2-dev libxslt-dev lib32z1-dev python3-dev



### Python libraries



Create a Python 3.4+ virtualenv and activate it.



Ensure `pip` and `setuptools` are up to date.



    pip install -U pip setuptools



For a production deployment, choose your database and install the requirements:



    # PostgreSQL

    pip install -r requirements/postgresql.txt

    

    # MySQL/MariaDB

    pip install -r requirements/mysql.txt



### Configuring



Create local config:



    cp social_relay/local_config.py.example social_relay/local_config.py



Edit the `local_config.py` file as instructed in the file.



### Database



You can set database connection settings as environment variables or in `social_relay/local_config.py` - see `social_relay/config.py` for what to override.



The database needs an initial schema creation. Do this with:



    arnold up 0



The same command should always be run when fetching new relay code. It will migrate any new schema changes.



### RQ Dashboard



An RQ dashboard can be found at `/rq`. Enable it in `social_relay/local_config.py` by setting `RQ_DASHBOARD = True`.

You must also set a username and password in the same file.



### Static files



Bower is used to pull in some JavaScript libs. [Install it first](http://bower.io/) if needed. Then run `bower install`.



Statics are server under the `/static` path which should be server by the web server.



### Running tasks and workers



Scheduled jobs handle the polling of node lists and nodes themselves, to fetch their subscription settings. Without the scheduled jobs the server will not be able to function. RQ workers on the other hand process all the incoming payloads and distribute them onwards to subscribing nodes. At least one RQ worker must be running at all times.



In production, it's easiest to use the provided `circus` configuration. This is installed via the provided production requirements, or `pip install circus` if not using the provided requirements file.



Then, export how many RQ workers you want. If you see your `receive` queue build up, increase this count and restart `circus`.



    export RQWORKER_NUM=5



To start `circus`, virtualenv activated in the project folder:



    circusd extras/circus/circus.ini

    

You can daemonize `circus` by passing an extra `--daemonize` flag.



#### Running tasks manually (without circus)



If you don't want to use `circus`, run the tasks manually.  Keep this running:



    python -m tasks.schedule_jobs



#### Processing receive queue (without circus)



If you don't want to use `circus`, run the workers manually. Run the worker(s) as follows:



    rqworker -c social_relay.config receive



## Deployment



Pretty much normal Python + WSGI setup, just install the requirements and serve app using WSGI and statics via the web server. See the following sections for platform specific helpers.



An Apache2 site example can be found [here](https://git.feneas.org/jaywink/social-relay/tree/master/ansible/roles/socialrelay/templates/apache.conf.j2). The same folder also has examples for upstart init jobs.



### Ansible (Ubuntu)



An Ansible role written for Ubuntu is provided in `ansible` directory. The role uses PostgreSQL, uWSGI and Apache. It will run also the scheduled jobs and a worker. Everything is handled by upstart.



Tested with Ubuntu 14.04 LTS.



### SystemD service files



There are example systemd service files in the 'extra' directory. The examples

use a specific user and utilize gunicorn. They have been tested on CentOS 7.



To use, modify as needed (user, group, and path), copy to `/etc/systemd/service`

and start/enable as such:



    systemctl start social-relay_server.service

    systemctl start social-relay_tasks.service

    systemctl start [email protected]

    systemctl start social-relay.target



    systemctl enable social-relay_server.service

    systemctl enable social-relay_tasks.service

    systemctl enable [email protected]

    systemctl enable social-relay.target



The rqworker service file can also be used to start the optional `failed` queue as well.



    systemctl start [email protected]



## Development



### Development requirements



    pip install -r requirements/development.txt

    

Ensure also `bower` is installed.



    npm install bower

    bower install



### Running a development server



This is not the recommended way for a production server. For testing and development, run the server:



    python devserver.py

    

The app will be running at [http://127.0.0.1:5000](http://127.0.0.1:5000).



### Running an RQ worker



    rqworker -c social_relay.config receive



### Running tests



Ensure there is a test database. By default the tests try to connect to PostgreSQL with db, username and password `socialrelaytest`.



Then run test with:



    py.test



### Maintaining dependencies



When changing requirements, use pip-tools.



    pip install pip-tools

    

To compile all



    ./compile-requirements.sh



## Author



Jason Robinson / @jaywink / https://jasonrobinson.me



Awesome contributors listed in `CONTRIBUTORS` file.



## License



AGPLv3