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.
Original idea for the relay system can be found in the diaspora* project wiki.
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 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. 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.
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