atomjump/loop-server

A server to the open messaging client AtomJump Loop https://atomjump.com

Thursday, June 21, 2018
by AtomJump
Repository
2 Watchers
1 Stars
3 Installations

PHP
0 Dependents
0 Suggesters
2 Forks
0 Open issues
82 Versions
0 % Grown

The README.md

, _(*1)

WARNING: this project has now moved to https://src.atomjump.com/atomjump/loop-server.git, _(*2)

AtomJump Messaging Server

This acts as a server to the AtomJump Messaging front-end at http://src.atomjump.com/atomjump/loop, _(*3)

Requirements

PHP. This software has been fully tested on PHP 5.3, 5.5, 7.0, 7.1, 7.2, 7.4 (with curl, php-mbstring, zip, php-xml support added). Note: Preliminary tests have been carried out with PHP 8.0 and 8.1, and most features appear to work, but we cannot yet guarantee 100% compatibility, although this will come in time.
MySQL 5+
Apache 2
Linux server (though a Windows server may be partially functional)

Recommended pre-installation steps

Modify the upload size in php.ini (found in e.g. /etc/php5/apache2/php.ini), _(*4)

upload_max_filesize = 10M
max_execution_time = 200
sudo service apache2 reload

Imagemagick can be used to handle image uploads (Ubuntu command):, _(*5)

sudo apt-get install imagemagick

To keep timing in-sync (Ubuntu command):, _(*6)

sudo apt-get install ntp

MySQL >= 5.7 users: add this 'SQL mode' into your my.cnf MySQL configuration file (found in e.g. /etc/mysql/mysql.conf.d/mysqld.cnf), _(*7)

sql_mode = STRICT_TRANS_TABLES

and restart the MySQL server with, _(*8)

sudo service mysql restart

Optional Components

Multi-server MySQL clusters (single-write or multi-write)
Load balancers with haproxy
SSL messaging server
SSL database connection

Installation

On your Linux server, download and unzip the latest release of the loop-server from https://src.atomjump.com/atomjump/loop-server/releases, _(*9)

https://src.atomjump.com/atomjump/loop-server/releases

Or git clone, _(*10)

git clone https://git.atomjump.com/loop-server.git

Or using composer https://getcomposer.org/ see https://packagist.org/packages/atomjump/loop-server, _(*11)

composer require atomjump/loop-server

We will refer to paths as being from the root of the loop-server folder., _(*12)

/server folder. You can refer to some example server configuration files. Replace atomjump with your own domain, and put any relevant files into your Apache 'sites available' setup. You may need to restart Apache., _(*13)
/config/configORIGINAL.json. Copy this file to /config/config.json. Replace the options with your own accounts and paths. Copy /config/messagesORIGINAL.json to /config/messages.json. Replace these options with your own words or languages., _(*14)
Allow image uploads, and image caching by the browser, _(*15)

a2enmod expires
chmod 777 /images/im

Copy /SET_AS_htaccess to /.htaccess and replace atomjump.com with your domain in this file., _(*16)
Customer defined themes must be on a secure server if the server is on ssl., _(*17)
To the ajFeedback object in your index.html, add a parameter, _(*18)

 "server": "http://yourserver.com"

In a MySQL prompt, run 'create database atomjump'. Then from the command line:

 mysql -u youruser -p atomjump < db/atomjump-loop-shell.sql

Optional Installation

Add three cron tasks to your server:, _(*19)

A typing cleanup task. On rare instances, a 'typing...' message is left (if the machine cut out etc.). This cleans up any of these old messages periodically (every 5 minutes)., _(*20)
A system monitoring warning, that checks whether the server's CPU or disk space have gone over a threshold. See warningDiskUsage, warningCPUUsage in the "Server Options" section, for more details., _(*21)

sudo crontab -e  
*/5 * * * * /usr/bin/php /yourserverpath/typing-cron.php  
sudo crontab -e  
*/5 * * * * /usr/bin/php /yourserverpath/monitor.php

A sentiment analysis task. This sentiment is reflected when you download a spreadsheet of the messages. It requires nodejs to be installed and available to be run by a cron job.

On your internet server, first install NodeJS and npm. See Ubuntu install notes at https://www.digitalocean.com/community/tutorials/how-to-install-node-js-on-an-ubuntu-14-04-server, but there are several ways to do this depending on your platform e.g. MacOSX may vary slightly., _(*22)

cd /yourserverpath/node  
npm install  
sudo crontab -e  
 */1 * * * * /usr/bin/nodejs /yourserverpath/node/sentiment.js -production

This will update the production database message sentiments once every minute (or remove the -production to go to staging)., _(*23)

Windows installation

Running on Windows has currently not been tested, but you can use a Ubuntu 14.04 virtual machine from https://bitnami.com/stack/lamp/virtual-machine, _(*24)

Messaging Client

(sometimes called the 'loop' project), _(*25)

Is available from https://src.atomjump.com/atomjump/loop#loop or you can add this to your site from http://atomjump.org/wp/add-atomjump-messaging-to-your-site/, _(*26)

This tool provides a 'WhatsApp-like' group discussion forum from a popup on your website. It is good for general messaging, either within a company or family, in either a private or public setting., _(*27)

The client software is entirely Javascript and CSS, but it refers to an AtomJump Messaging server to store messages. This is freely available as a separate project at https://src.atomjump.com/atomjump/loop-server, or you can use the AtomJump.com server, by default., _(*28)

Private forums on the hosted AtomJump.com hosted platform are purchased for US$10 / year to cover the (non-profit) Foundation's costs, but public forums are free, within reason., _(*29)

Supported client platforms: IE8 upwards, Edge, Chrome, Firefox, Safari, Android Native, Android Chrome, Android Firefox, iPad, iPhone, Opera. There may be other supported platforms we haven't tested on., _(*30)

See the demo at AtomJump, _(*31)

You can adjust the styling by making changes to the CSS file for your project., _(*32)

Client Installation

With bower from within the root of your project path:, _(*33)

bower install atomjump, _(*34)

(Or without bower, unpack into your project, edit index.html, and replace bootstrap css and javascript paths as mentioned), _(*35)

Run atomjump/index.html in your browser. You should see a 'Click me for comments' link. Click this to see the pop-up. For Wordpress instructions, see below., _(*36)

Client Setup

Look carefully at the index.html example., _(*37)

The code between , _(*38)

and , _(*39)

should be put into your page's <head> section., _(*40)

Links can be added to the comments with <a class="comment-open" href="javascript:">Click me for comments</a>, _(*41)

The code <div id="comment-holder"></div> must be placed anywhere in the <body> section., _(*42)

Note: jQuery ver 1.9.1 is used. Other jQuery versions will likely work also., _(*43)

Adjust 'uniqueFeedbackId' value to a unique value to suit your forum's name. This can be unique per page or the same throughout the whole site., _(*44)
For messaging usage, refer to the Messaging guide at http://atomjump.org/wp/user-guide/, _(*45)

To have more than one messaging forum on a single page

You can do this three different ways. The simplest is to set the link's href to '"#comment-open-' followed by the forum name: <a href="#comment-open-my_different_forum_name">Open special forum</a>, _(*46)

Or, you can add the 'comment-open' class to a link with an 'id' referring to the forum name (you also need a 'data-useid' tag): <a class="comment-open" id="my_different_forum_name" data-useid="true" href="javascript:">Open special forum</a>, _(*47)

Or, for further control over the owner of the forum, you can add the following data tags, and enter your own names/ips: <a class="comment-open" data-uniquefeedbackid="my_different_forum_name" data-mymachineuser="10.12.13.14:2" href="javascript:">Open special forum</a>, _(*48)

To open custom URLs within notifications

When the app or email setup sends notifications, it provides a clickable address for the user to go to in order to see the forum. If the usual current web address is behind a token or password, this link needs a lead-up page to allow for client-side logins. You can set this address with the 'data-notifyurl' token., _(*49)

<a class="comment-open" data-notifyurl="https://myurl.behind/?token=password-protected-page" href="javascript:">Open with specific notification URL</a>, _(*50)

To open a Shortmail enabled forum

You can add the 'shortmail' data tag e.g., _(*51)

<a class="comment-open" data-uniquefeedbackid="my_different_forum_name" data-mymachineuser="10.12.13.14:2" data-shortmail="true" href="javascript:">Open special email forum</a>, _(*52)

Or, you can use an href "#shortmail-open-" class: <a href="#email-open-my_shortmail_forum_name">Open shortmail forum</a>, _(*53)

To change the theme

Add, _(*54)

"cssBootstrap":"relative/url", _(*55)

and, _(*56)

"cssFeedback":"relative/url/to/your/css", _(*57)

to the ajFeedback object., _(*58)

Note: your css file must be on an https server, if your server is using https., _(*59)

To download a forum's messages programmatically

Endpoint http://yourserver.com/download.php, _(*60)

or for atomjump.com's web-service:, _(*61)

https://atomjump.com/api/download.php, _(*62)

Parameters, _(*63)

email Your AtomJump Loop email address from the standard interface
pass
Your AtomJump Loop password
uniqueFeedbackId
The particular forum to view. Note: include 'ajps_' at the start of this string for x.atomjump.com forums.
from_id
There is a limit of 2000 records per request. To download more, include the 'id' of the last record, from the previous download request, in this field.

Which returns a JSON object. Included for reporting is a 'sentiment' field which measures how positive the comment is (< 0 negative, 0= neutral, > 0 positive)., _(*64)

Getting a live sentiment

Include the following parameters along with 1,2, and 3 above., _(*65)

format, _(*66)

Set to 'avg', _(*67)
duration, _(*68)

Period over which to average in seconds., _(*69)

The response will be an average over the last period of all the message sentiment values. This will be expressed as a single number eg. 5.324. Note: it can take up to 1 minute before any new message's sentiment will be calculated., _(*70)

Wordpress Setup

Install the ‘Header and Footer’ plugin. https://wordpress.org/plugins/insert-headers-and-footers/
Go into ‘Settings->Header and Footer’, and enter the two sections from http://atomjump.org/wp/add-atomjump-messaging-to-your-site/. The main block should be entered into the ‘SECTION INJECTION’ section, and the ‘comment holder’ div should be entered into the ‘BEFORE THE CLOSING TAG (FOOTER)’ section.
Any link’s address (i.e. the ‘href’) on the page can now start with ‘#comment-open-‘, followed by the forum name and it will open a popup.

For more details see http://atomjump.org, _(*71)

Server Options

Staging: To ensure you are set to staging, set the 'usingStaging' param to 'true'., _(*72)

To test the web domain, use the following small PHP script:, _(*73)

<?php
        echo "Server name:" . $_SERVER['SERVER_NAME'];
?>

warningDiskUsage: After this certain percentage (0-100) of the current disk space is used, we provide an external service, such as Nagios, with the ability to provide a warning that the server is nearing it's disk capacity. It does this by creating a folder in the main directory /images/im/capacity/ and putting a file 'within-disk-capacity-warning.html' into this folder. If the file is visible externally, the server's drive space is normal, but if this file is not visible (and therefore returns a 404 http error message, typically) then the server's disk space is beyond this threshold and is nearing it's capacity. Ver >= 2.8.4, _(*74)

warningCPUUsage: After this certain percentage (0-100) of the CPU load is used, we provide an external service, such as Nagios, with the ability to provide a warning that the server is nearing it's capacity of CPU usage. It does this by creating a folder in the main directory /images/im/capacity/ and putting a file 'within-cpu-capacity-warning.html' into this folder. If the file is visible externally, the server's CPU is normal, but if this file is not visible (and therefore returns a 404 http error message, typically) then the server's CPU is beyond this threshold and is nearing it's capacity. Ver >= 2.8.4, _(*75)

db hosts: there can be any number of db hosts, but some services do not allow multiple write hosts, and if this case the first one is the only write host, while the others are read. You can configure this with the 'singleWriteDb' option., _(*76)

db maxConcurrentUsers: Caps the number of users at a certain number of concurrent connections, and does not try to open the forum if there are too many users, providing a warning to come back later. The actual number of users supported will be many more than this figure as they will not all be requesting from the database at once, and many will only be reading rather than writing, but this level roughly indicates a situation where everyone is typing at the same time. Ver >= 2.8.1, _(*77)

db warningConcurrentUsers: After a certain number of concurrent connections (this number is usually less than maxConcurrentUsers), we provide an external service, such as Nagios, with the ability to provide a warning that the server is nearing it's capacity of concurrent users. It does this by creating a folder in the directory /images/im/capacity/ and putting a file 'within-db-capacity-warning.html' into this folder. If the file is visible externally, the server is within capacity, but if this file is not visible (and therefore returns a 404 http error message, typically) then the server is nearing it's capacity, and will shortly produce a warning to users that the forum has too many users. Ver >= 2.8.4, _(*78)

db singleWriteDb: optional. 'true' for a single write database cluster, and 'false' for a multiple write database cluster. This option is only applicable if there is more than one database host. Ver >= 1.8.9, _(*79)

db scaleUp: For different forums you can refer to completely different databases, to remove the heavy write usage in a multi-read/single write database server farm. This is an array of alternative db/hosts, which are used if a given regular expression is detected in the forum's name., _(*80)

db scaleUp labelRegExp: This is a javascript/PHP regular expression that changes the database used for this forum. E.g. "^hello", would detect the forums 'hello_there', 'hello_anything' etc. Then the standard db details can be entered for this case i.e. 'name','hosts','user','pass','port','deleteDeletes','timezone','serviceHome'. You can also have different set of plugins with a unique 'plugins' array (Ver >= 1.9.5)., _(*81)

(Ver >= 2.9.0) You can optionally run the sentiment script on another database in your configuration file, for example for forums starting with "api1" by using:, _(*82)

sudo crontab -e
*/1 * * * * /usr/bin/nodejs /yourserverpath/node/sentiment.js -production -labelregexp ^api1

db ssl: Makes the connection to the database encrypted. Ver >= 1.9.5, _(*83)

"ssl" : {
            "use" : false,
            "key" : "",
            "cert" : "",
            "cacert": "",
            "capath": "",
            "protocol": "",
            "verify": true
         }

db ssl use: Set to 'true' to use SSL, or 'false' to ignore the SSL settings and transfer data to the database unencrypted. Ver >= 1.9.5, _(*84)

db ssl key: The file path of the server's key file. Ver >= 1.9.5, _(*85)

db ssl cert: The file path of the server's certificate file. Ver >= 1.9.5, _(*86)

db ssl cacert: The file path of the CA Certificate file. Ver >= 1.9.5, _(*87)

db ssl capath: The path to the folder that contains the CA Certificate file. Ver >= 1.9.5, _(*88)

db ssl protocol: A list of the supported ssl protocols (separated by semi-colons). Ver >= 1.9.5. Here are some common protocols:, _(*89)

``` ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA:ECDHE-ECDSA-AES256-SHA:DH-DSS-AES256-GCM-SHA384:DHE-DSS-AES256-GCM-SHA384:DH-RSA-AES256-GCM-SHA384:DHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES256-SHA256:DHE-DSS-AES256-SHA256:DH-RSA-AES256-SHA256:DH-DSS-AES256-SHA256:DHE-RSA-AES256-SHA:DHE-DSS-AES256-SHA: DH-RSA-AES256-SHA:DH-DSS-AES256-SHA:DHE-RSA-CAMELLIA256-SHA:DHE-DSS-CAMELLIA256-SHA:DH-RSA-CAMELLIA256-SHA:DH-DSS-CAMELLIA256-SHA:ECDH-RSA-AES256-GCM-SHA384:ECDH-ECDSA-AES256-GCM-SHA384:ECDH-RSA-AES256-SHA384:ECDH-ECDSA-AES256-SHA384:ECDH-RSA-AES256-SHA:ECDH-ECDSA-AES256-SHA:AES256-GCM-SHA384:AES256-SHA256:AES256-SHA:CAMELLIA256-SHA:PSK-AES256-CBC-SHA:ECDHE-RSA-AES128-GCM-SHA256: ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-SHA256:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA:ECDHE-ECDSA-AES128-SHA:DH-DSS-AES128-GCM-SHA256:DHE-DSS-AES128-GCM-SHA256:DH-RSA-AES128-GCM-SHA256:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES128-SHA256:DHE-DSS-AES128-SHA256:DH-RSA-AES128-SHA256:DH-DSS-AES128-SHA256:DHE-RSA-AES128-SHA:DHE-DSS-AES128-SHA:DH-RSA-AES128-SHA:DH-DSS-AES128-SHA:DHE-RSA-SEED-SHA:DHE-DSS-SEED-SHA:DH-RSA-SEED-SHA:DH-DSS-SEED-SHA:DHE-RSA-CAMELLIA128-SHA: DHE-DSS-CAMELLIA128-SHA:DH-RSA-CAMELLIA128-SHA:DH-DSS-CAMELLIA128-SHA:ECDH-RSA-AES128-GCM-SHA256:ECDH-ECDSA-AES128-GCM-SHA256:ECDH-RSA-AES128-SHA256:ECDH-ECDSA-AES128-SHA256:ECDH-RSA-AES128-SHA:ECDH-ECDSA-AES128-SHA:AES128-GCM-SHA256:AES128-SHA256:AES128-SHA:SEED-SHA:CAMELLIA128-SHA:IDEA-CBC-SHA:PSK-AES128-CBC-SHA:ECDHE-RSA-RC4-SHA:ECDHE-ECDSA-RC4-SHA:ECDH-RSA-RC4-SHA:ECDH-ECDSA-RC4-SHA: RC4-SHA:RC4-MD5:PSK-RC4-SHA:ECDHE-RSA-DES-CBC3-SHA:ECDHE-ECDSA-DES-CBC3-SHA:EDH-RSA-DES-CBC3-SHA:EDH-DSS-DES-CBC3-SHA:DH-RSA-DES-CBC3-SHA:DH-DSS-DES-CBC3-SHA:ECDH-RSA-DES-CBC3-SHA:ECDH-ECDSA-DES-CBC3-SHA:DES-CBC3-SHA:PSK-3DES-EDE-CBC-SHA, _(*90)

**db** **ssl** **verify**: Whether to require verification of the certificates. We strongly recommend this is set to 'true'. 'false' requires PHP ver >= 5.6. Ver >= 1.9.5

**ips**: any number of PHP machines with the server software on it.

**webRoot**: Web path including http/https of the server. Don't include trailing slash.

**fileRoot**: Local file system server's file path. Don't include trailing slash.

**serviceHome**: The homepage of the service as a URL. This is used particularly after resetting a password.

**serverTimezone**: Change this to the location of the physical server eg. Pacific/Auckland

**delayFeeds**: Delays any API or feed download access for this number of seconds. The default is 1200 seconds or 20 minutes.

**titleReplace** **regex** **replaceWith**: To create an automatic visual title for a forum based off the forum's actual database name, you should add in any regular expression replacements. This should be an array of { regex, replaceWith } objects, which are processed sequentially on the forum's database name. For example, xyz.atomjump.com pages are given a forum database name ajps_Xyz . The regex to replace the "ajps_" part of this to create a title "Xyz" you should should use
{
"regex": "/ajps_(.+)/",
"replaceWith": "$1"
}
Where $1 is the entry in (.+). Note: you should include the /expression/ around your expressions, and can optionally include case insensitive modifiers, e.g. /expression/i.
More information on the supported expressions is available at https://www.php.net/manual/en/function.preg-replace.php.
You can switch automatic titles on or off with 'showAutomaticTitle' below.

**showAutomaticTitle** can be 'true' or 'false' depending on whether you wish to auto-generate titles for the forum headers. You can also modify the title using the 'titleReplace' options above.

**deleteDeletes**: Set to true by default, this means any user action to delete a message removes it completely from the database. If for your records you are required to keep hidden messages, set to false.

**loadbalancer**: Required for a production setup - any number of machines. Can be blank in a staging setup.

**phpPath**: Path to externally run any parallel PHP processes. Ver >= 0.5.5

**chatInnerJSFilename**: Path from the server that refers to the server-side Javascript. E.g. "/js/chat-inner-1.3.29.js". This will override the system default, if the file exists, but otherwise the default version is used, which is specified at the top of the search-secure.php script.

**logoutPort**: Depreciated ver 0.6.3. Port which a logout is supported on. Default 1444. Use in an ssh situation, whereby this is a non-ssh port. Ver >= 0.5.5, ver <= 0.6.2

**adminMachineUser**: once your server has been set up, and you have saved your first user (yourself typically), find this user in the interface
Advanced settings, and write this into the config. This user is allowed to set forum passwords and limit the subscribers for a particular forum.

**analytics** **use**: Can be 'none'. Include a 'url' entry. The 'image' field is currently only needed for retrieving unique backgrounds for subdomains of atomjump.com.

**social** **use**: Can be 'none' or 'all'. 'none' switches off all social media interaction, while 'all' enables all of them.

**social** **twitter**: optional. Retrieves tweets from twitter related to this subdomain, and allows for replying to the tweets (posts a
message via twitter).

**readPort**: optional. The port to put the plugin 'loop-server-fast' daemon on, if it is different to 3277, see https://www.npmjs.com/package/loop-server-fast. Ver >= 0.5.22.

**readURL**: optional. The full URL including ports that the plugin 'loop-server-fast' daemon is on, see https://www.npmjs.com/package/loop-server-fast, if this is different to the standard URL followed by 'readPort'. Note: if you use a non-standard port, some machines behind proxy servers, particularly corporates, or some public PCs may have the address filtered out. One approach here, at a slight loss of speed, is to use the standard port 80 for http and 443 for https, and ProxyPass in Apache. Ver >= 1.5.5.

**httpsKey**: optional. If you are serving from an https address, you will need this local file path, for the plugin 'loop-server-fast', see https://www.npmjs.com/package/loop-server-fast. See also 'httpsCert', which is needed too. Ver >= 0.5.22

**httpsCert**: optional. If you are serving from an https address, you will need this local file path, for the plugin 'loop-server-fast', see https://www.npmjs.com/package/loop-server-fast. See also 'httpsKey', which is needed too. Ver >= 0.5.22

**uploads** **use**: This can be one of 'none', 'same', 'generic', 'amazonAWS'. 'none' means uploads are switched off. 'same' means the upload stays on the same server in the '/images/im/' folder. 'generic' means uploads.genericUploadURL should be set to a remote URL, which the image file will be uploaded to via a POST request. 'amazonAWS' refers to the use of an Amazon S3 AWS bucket for remote storage. You will need an Amazon 'accessKey', 'secretKey' and 'imageURL', in this case.

Note: You should make sure your server provides a caching response to image files, or Safari will continue to refresh the images every 5 seconds.

**uploads** **hiRes** **width** (**height**): width in pixels of uploaded images, in their hi-res version. The low-res version is displayed to the whole group, and the hi-res version is only used when a user taps on that one photo.

**uploads** **lowRes** **width** (**height**): width in pixels of uploaded images, in their low-res version. The low-res version is displayed to the whole group, and the hi-res version is only used when a user taps on that one photo.

**uploads** **replaceHiResURLMatch**: set to a string in your uploaded images URL path that identifies that the photo is on your server, and not copied from a different server e.g. 'atomjump' would identify for "http://yourserver.com/atomjump/images/im/yourphoto.jpg". Images which include this string, will show the hi-res uploaded version when clicked e.g. "http://yourserver.com/atomjump/images/im/yourphoto_HI.jpg".

**uploads** **imagesShare**: If there are multiple PHP nodes, this defines which port to write uploaded images to, so that they are shared between nodes. 'port' is a port such as 80, and 'https' is either true or false. 'checkCode' is a unique code to your server, which you should change, for security purposes, to allow access from your nodes, only, Ver >= 2.5.7. If you are setting up an expandable cluster, you should also modify images/im/.htaccess and enter your subfolder path where it says CHANGE THIS BELOW, to provide a 'missing images' handler that allows expanding clusters, Ver >= 2.5.7.

**uploads** **vendor** **amazonAWS**: optional. This is for S3 storage of uploaded images. You will need an Amazon 'accessKey', 'secretKey' and 'imageURL', in this case.

**email** **adminEmail**: Administrator's email address.

**email** **webmasterEmail**: The webmaster's email address.

**email** **noReplyEmail**: An email address for when you do not want a reply.

**email** **sending** **use**: This can be 'none', 'smtp' or 'mailgun'. 'none' means there are no emails sent as notifications. 'smtp' means a standard SMTP server is used, and you should enter the 'smtp' which is the host, 'user' which is the username, typically the email address, 'pass' which is the password, 'encryption' which can be 'tls', 'ssl' or left blank, and the 'port' which is the SMTP port number used. 'mailgun' means the Mailgun.com service is used and you will need a 'key' and 'url' from Mailgun.

For example, atomjump.com uses http://smtp2go.com, who provide an excellent email sending service:

"smtp": "mail.smtp2go.com", "user" : "...@atomjump.com", "pass": "...", "port": "2525", _(*91)


**email** **sending** **vendor** **mailgun**: optional. You need a mailgun account which has about 10,000 free emails per month, but costs after that. You will need a 'key' and 'url' from Mailgun.

**sms** **use**: This can be 'none' or 'twilioSMS'. None switches off SMS.

**sms** **twilioSMS**: optional. Required for sending off SMSes via Twilio.

**sms** **USDollarsPerSMS**: for reporting purposes only. This is what is shown to users if they choose to use the SMS notifications.
Since there is a cost to you for each SMS, you will likely set this slightly higher than the actual cost of an SMS, to
account for fluctuations in price.


# Changing language packs

Please see the /config/language-packs/README.md file for instructions on changing which languages are available to your users.


# Plugins

Plugins can be installed in the /plugins directory.
See http://atomjump.org/wp/plugin-summary/ for a list of plugins available.


## Plugin API

For a sample plugin called 'hide_aargh':

/plugins/hide_aargh/index.php

```php
<?php
    include_once("classes/cls.pluginapi.php");

    class plugin_hide_aargh
    {
        public function on_message($message_forum_id, $message, $message_id, $sender_id, $recipient_id, $sender_name, $sender_email, $sender_phone)
        {
            //Do your thing in here. Here is a sample.
            $api = new cls_plugin_api();

            //e.g. hide the message we have just posted if it includes the string 'aargh' in it.
            if(strpos($message, 'aargh') !== false) {
                $api->hide_message($message_id);
            }

            return true;

        }
    }
?>

Add the entry "hide_aargh" to the "plugins" array in config/config.json to activate the plugin., _(*92)

Reading functions

db_insert(), _(*93)

Parameters ($table, $insert_field_names_str, $insert_field_data_str)
Server: >= 0.5.0, _(*94)

  $table                     //AtomJump Loop Server ('atomjump' by default) database table name eg. "tbl_email"
  $insert_field_names_str    //Insert string e.g. "(var_layers, var_title, var_body, date_when_received, var_whisper)"
  $insert_field_data_str     //Insert values e.g. ('" . clean_data($feed['aj']) . "','". clean_data($subject) . "','" . db_real_escape_string($raw_text) .  "', NOW(), '" . $feed['whisper'] . "') " )

db_select(), _(*95)

Parameters ($sql)
Server: >= 0.5.0, _(*96)

An ordinary SELECT SQL query., _(*97)

db_update(), _(*98)

Parameters ($table, $update_set)
Server: >= 0.5.0, _(*99)

Update_set is the SQL after an 'UPDATE table SET' e.g. "var_title = 'test' WHERE var_title = 'test2'" - can have multiple fields, _(*100)

db_fetch_array(), _(*101)

Parameters ($results)
Server: >= 0.5.21, _(*102)

Get an array of rows from a database query., _(*103)

db_real_escape_string(), _(*104)

Parameters ($string)
Server: >= 0.5.21, _(*105)

Ensure the string is escaped for input into the database., _(*106)

db_error(), _(*107)

No parameters Server: >= 0.5.21, _(*108)

Returns the database error text., _(*109)

db_insert_id(), _(*110)

No parameters Server: >= 0.5.21, _(*111)

Get the last database inserted id field value., _(*112)

get_forum_id(), _(*113)

Parameters ($message_forum_name)
Server: >= 0.5.0, _(*114)

Output is an array:
[ forum_id, access_type, forum_group_user_id, requires_password ]

Where 'forum_id' e.g. 34
      'access_type' eg. "readwrite", "read"
      'forum_owner_user_id' is the user id to send a message to, to become visible to all the private forum owners.
      'requires_password' is 'true' if the forum is password protected, or 'false' if not. (Server >= 2.3.4)

get_current_user_ip(), _(*115)

No parameters
Server: > 0.5.0, _(*116)

Get the user's ip address, although this is now an artificial ip address, actually a unique 'ip' based off their user id., _(*117)

get_current_user_id(), _(*118)

No parameters
Server: >= 0.5.0, _(*119)

Returns the integer user id value of the current user., _(*120)

is_admin(), _(*121)

Required Parameters ($user_id) Server: >= 3.2.2, _(*122)

Returns: true/false, _(*123)

is_forum_granted(), _(*124)

Required Parameters ($check_forum_id)
Server: >= 2.3.4, _(*125)

Check if a layer (numerical ID) has been granted access (i.e. the password has been specifically entered by the current user). If there is no need for access to be granted (i.e. on a public forum - see get_forum_id() and 'requires_password' return param) you should ignore any 'false' values., _(*126)

Returns: true/false, _(*127)

Hooks

on_message(), _(*128)

Output parameters ($message_forum_id, $message, $message_id, $sender_id, $recipient_id, $sender_name, $sender_email, $sender_phone, $message_forum_name)
Plugin function returns
(true)
Server: >= 0.5.1 ($message_forum_name >= 0.7.6), _(*129)

Occurs after a message being posted., _(*130)

before_message(), _(*131)

Output parameters ($message)
Plugin function returns
($message)
Server: >= 0.5.0, _(*132)

Occurs just before a message is posted, allowing changes to the message text., _(*133)

on_more_settings(), _(*134)

Output parameters ($message)
Plugin function writes HTML inside ordinary PHP tags e.g., _(*135)

?>Your settings HTML<?php

Server: >= 0.5.9, _(*136)

on_save_settings(), _(*137)

Output parameters ($user_id, $full_request: array of options, $type: NEW or SAVE) Plugin function returns
(true/false), _(*138)

Called when the settings are saved. $user_id is the integer user's id being saved. $full_request is the $_REQUEST array with the user's entered values. $type can be 'NEW' if it is a new record, or 'SAVE' to save an existing record., _(*139)

on_upload_screen(), _(*140)

Output parameters ($message)
Plugin function writes HTML inside ordinary PHP tags e.g., _(*141)

?>Your settings HTML<?php

Server: >= 0.5.9, _(*142)

on_msg_buttons(), _(*143)

Output parameters ($message_id) Plugin function should return ($html), _(*144)

When a particular message is clicked, a screen with more options (e.g. deleting the message) appears. This plugin function should return the HTML for the new custom button directly, including a javascript onclick="" event, and code, such as a server 'get' request to handle that event., _(*145)

Server: >= 2.2.8, _(*146)

on_notify(), _(*147)

Output parameters ($stage, $message, $message_details, $message_id, $sender_id, $recipient_id, $in_data)
Plugin function should return ($ret, $ret_data) where $ret is true, unless a recipient is not to get a message, when your plugin function should return $ret = false, _(*148)

$ret_data should be used to forward the data on to the next stage function, in the $in_data parameter., _(*149)

Server: >= 0.7.7, _(*150)

This hook allows you to embed custom code into a notification e.g. the plugin 'notifications' uses this function to send messages to the AtomJump phone app., _(*151)

Used at 3 stages of the notification process, defined by $stage. Stages are:, _(*152)

1. init          - this call occurs once the first notification in a group is reached
2. addrecipient  - this occurs for each recipient in the group
3. send          - this occurs on being ready to send

$message_details will be an array in the following format:, _(*153)

array("observe_message" => $observe_message,        //This is the message to be written next to the visual link to the forum
         "observe_url" => $observe_url,             //This is the URL of the visual link to the forum
         "forum_message" => $layer_message,         //A message that preceeds the name of the forum the message was sent from
         "forum_name" => $layer_name,               //The name of the forum the message was sent from
         "remove_message" => $remove_message,       //A description of what to do to remove the message
         "remove_url" => $remove_url);              //The URL to remove the message

Writing functions

new_message(), _(*154)

Required Parameters ($sender_name_str, $message, $recipient_ip_colon_id, $sender_email, $sender_ip, $message_forum_id, $options)
Server: >= 0.5.0, _(*155)

Optional Parameters in an $options object: ($sender_still_typing, $known_message_id, $sender_phone, $javascript_client_msg_id, $forum_owner_id, $social_post_short_code, $social_recipient_handle_str, $date_override, $latitude, $longitude, $login_as, $allow_plugins, $allowed_plugins, $notification, $always_send_email)
Server: >= 0.5.0, _(*156)

Additions: ($login_as), server >= 0.5.1
($allow_plugins, $allowed_plugins), server >= 0.5.5 ($notification, $always_send_email), server >= 1.0.4 ($strip_tags), server >= 3.2.3, _(*157)

Output parameters ($message_id), _(*158)

    $sender_name_str,                           //e.g. 'Fred'
    $message,                                   //Message being sent e.g "Hello world!"
    $recipient_id,                              //User id of recipient e.g. "123.123.123.123:436" 
    $sender_email,                              //Sender's email address e.g. "fred@company.com"
    $sender_ip,                                 //Sender's ip address eg. "123.123.123.123"
    $message_forum_id,                          //Forum id e.g. 23, which is derived from a forum name e.g. 'aj_test',
    $options                                    //Options array, see below

Options

    $sender_still_typing = false;               //Set to true if this is a partially completed message
    $known_message_id = null;                   //If received an id from this function in the past
    $sender_phone = null;                       //Include the phone number for configuration purposes
    $javascript_client_msg_id = null;           //Browser id for this message.
    $forum_owner_id = null;                     //User id of forum owner
    $social_post_short_code = null;             //eg 'twt' for twitter, 'fcb' for facebook
    $social_recipient_handle_str = null;        //eg. 'atomjump' for '@atomjump' on Twitter
    $date_override = null;                      //optional string for a custom date (as opposed to now) 
    $latitude = 0.0;                            //for potential future location expansion
    $longitude = 0.0;                            //for potential future location expansion
    $login_as = false;                          //Also login as this user
    $allow_plugins = false;                     //To prevent infinite message sending loops, we don't refer to any other plugins
                                                //after a message send
    $allowed_plugins = null;                    //Use the standard plugins (null), or an array of approved plugins from the plugin
                                                //developer. However, plugins that work with before_msg will continue to work 
    $notification = true;                       //Set to false to switch off notifications from this message
    $always_send_email = false;                 //Set to true to ensure an email will always be sent to the recipient(s). Usually, messages within around 20 minutes won't multiple-email the user (when false).
    $strip_tags = true;                         //By default we strip any tags in a new message

Usage example:, _(*159)

    $options = array('notification' => false);      //turn off any notifications from these messages


    $new_message_id = $api->new_message($helper, $new_message, $sender_ip . ":" . $sender_id, $helper_email, $sender_ip, $message_forum_id, $options);

Warning: if your plugin is a standalone script (as opposed to being called from the main server), you will need to also call, _(*160)

$api->complete_parallel_calls();

if you want the notifications to be sent, as these happen in parallel., _(*161)

hide_message(), _(*162)

Required Parameters ($message_id)
Server: >= 0.5.0, _(*163)

Optional Parameters ($warn_admin)
Server: >= 0.5.0, _(*164)

Hides a message from view, where $message_id is an integer. $warn_admin can be true/false to warn the owner of the forum of the message being hidden., _(*165)

Sending Emails, _(*166)

Although this is not yet a part of the plugin API, you can include the config/db_config.php file in your own script and use either the cc_mail_direct() or cc_mail() functions. The direct() version will immediately send an email (with an execution pause of a few seconds), while the regular version will log the request in parallel., _(*167)

You should set a global variable $notify beforehand, _(*168)

$notify = true;

See the 'Notifications' plugin at https://src.atomjump.com/atomjump/notifications/, script register.php for an example., _(*169)

If you use the regular cc_mail() version, you will need to also call, _(*170)

$api->complete_parallel_calls();

if you want the notifications to be sent, at the end of the script., _(*171)

Global Variables

$root_server_url The AtomJump Messaging Server's URL. Make the variable available to your function with:, _(*172)

global $root_server_url;

$cnf The global configuration file as an array. This can be accessed with e.g. $cnf['webRoot']. Make the variable available to your function with:, _(*173)

global $cnf;

$msg The global messages configuration file as an array. This can be accessed with e.g. $msg['msgs'][$lang]['description']. Make the variable available to your function with:, _(*174)

global $msg;

$lang The current selected language e.g. "en" for English. Make the variable available to your function with:, _(*175)

global $lang;

$db_cnf The current selected database configuration. This can be accessed with e.g. $db_cnf['user']. Make the variable available to your function with:, _(*176)

global $db_cnf;

$notify Allow email notifications to be sent if 'true'. You should set this within your own script. Please see the section 'Writing Functions > Sending Emails'., _(*177)

$_REQUEST['uniqueFeedbackId'] / $_REQUEST['passcode'] Either of these can be the current forum's name as a string. You should check for both., _(*178)

$_SESSION['logged-email'] Set on sign in. This is the email of the signed in user., _(*179)

$_SESSION['user-ip'] The logged-in user's artificial ip address., _(*180)

$_SESSION['temp-user-name'] This username is used potentially before another name is set e.g. 'Anon 55', _(*181)

$_SESSION['authenticated-layer'] The current user has the authority to read and write to this layer ID (applies to any forum, not just password protected forums)., _(*182)

Misc

parallel_system_call(), _(*183)

Required Parameters ($command)
Server: >= 0.5.5, _(*184)

Optional Parameters ($platform:'linux'/'windows' default:'linux'), _(*185)

Run a unix shell command in a parallel process. This allows e.g. a process to run in the background and after a period of time do some action. Also see complete_parallel_calls()., _(*186)

complete_parallel_calls(), _(*187)

No parameters., _(*188)

Server: >= 0.9.0, _(*189)

This should be called at the end of your script to complete all of the parallel_system_call() commands, if your script is a standalone script (i.e. not called via a hook). It will hard exit the script after completion, and close down the sessions., _(*190)

show_translated_number(), _(*191)

Required parameters ($number, $lang), _(*192)

Server: >= 2.6.7, _(*193)

Input, ideally an integer between 0 - 60 (60 seconds in a minute means this is usually the largest number we need for most things, i.e. 59 seconds ago), and a language e.g. "en", "ch" from the messages.json translation list. However, any number can be used and the default is to return the English number if there is no matching number in the messages array "number" conversion for the input language., _(*194)

Examples

All of the AtomJump-built plugins serve as good example code. But here are some particular cases:, _(*195)

Adding your own buttons, _(*196)

For customising the buttons that are visible when you tap on a single message, and for including a specific type of export of a forum, see this shell project, which can be modified to suit your own., _(*197)

https://src.atomjump.com/atomjump/medimage_export/tree/shell, _(*198)

Performance

Performance depends on a number of factors. In general, since the AtomJump Server can be configured with a load balancer, multiple PHP servers and multiple database servers, the number of users supported can scale almost by adding more servers to the cluster. The basic PHP script on one server should handle (in the order of) one hundred simultaneous users, but this will vary considerably on the hardware used, the amount of usage and the type of usage by these users., _(*199)

However, to extend performance into larger scale environments, we have released the NodeJS 'loop-server-fast' plugin at https://www.npmjs.com/package/loop-server-fast. This aims to scale to thousands, or tens of thousand, simultaneous users per server. You can start by installing the PHP version, and then install the NodeJS version as you expand (you can revert back to the PHP version, also, if you have any issues)., _(*200)

AtomJump Messaging can work in a single write/ multiple read MySQL cluster, or a multi-write / multi-read cluster. The latter should be scalable to millions of simultaneous users., _(*201)

Contributing

Contributions are welcome, and they can take the shape of:, _(*202)

Core: Submit github pull requests. We will need to consider whether the feature should be in core, or externally as a plugin. It is generally a good idea to get in touch with us via our homepage at http://atomjump.org to ensure we are not already working on a similar feature.
Plugins: Develop to the API above, and then publish on the http://atomjump.org/wp/plugin-summary/ 'available plugins' link. You are free to write or publish (or keep private) any number of plugins.
Translations: We are looking for any translations of the conf/messages.json file from English into your language. We have machine translated Spanish as a first step, but we need help in ensuring this is a good translation, and applying other languages.

License

This software is open source under the MIT license. Copyright is with the AtomJump Foundation (New Zealand), a non-profit society. You can use this software for any commercial purposes., _(*203)

Other credits

Ear and Help Icons designed by Roundicons https://www.flaticon.com/authors/roundicons from http://www.flaticon.com, and the other ear icon by Freepik https://www.flaticon.com/authors/freepik from the same site., _(*204)

The Versions

21/06 2018

dev-master

9999999-dev https://atomjump.com

A server to the open messaging client AtomJump Loop https://atomjump.com

library loop-server

A server to the open messaging client AtomJump Loop https://atomjump.com

atomjump/loop-server

The README.md

AtomJump Messaging Server

Requirements

Recommended pre-installation steps

Optional Components

Installation

Optional Installation

Windows installation

Messaging Client

Client Installation

Client Setup

To have more than one messaging forum on a single page

To open custom URLs within notifications

To open a Shortmail enabled forum

To change the theme

To download a forum's messages programmatically

Getting a live sentiment

Wordpress Setup

Server Options

Reading functions

Hooks

Writing functions

Global Variables

Misc

Examples

Performance

Contributing

License

Other credits

The Versions

dev-master

The Requires

by AtomJump

v1.7.0

The Requires

by AtomJump

v1.6.7

The Requires

by AtomJump

dev-gdpr

The Requires

by AtomJump

v1.6.6

The Requires

by AtomJump

v1.6.5

The Requires

by AtomJump

v0.5.10

v0.5.11

v0.5.6

v0.5.1

v0.5.3

v0.5.4

v0.5.5

v0.4.0

v0.5.0

v0.5.20

v0.5.21

v0.5.22

v0.5.17

v0.5.18

v0.5.19

v0.5.2

v0.5.14

v0.5.15

v0.5.16

v0.5.9

v0.6.0

v0.5.12

v0.5.13

V0.5.7

v0.5.8

v1.6.4

The Requires

by AtomJump

v1.6.3