Server User Guide
AtomJump Messaging Server
User Guide
- Once you have a server installed (see the Installation Guide), you then need to configure your /config/config.json file to match your intended usage. This configuration file has all the options that change how the Messaging Server behaves, and allows you to add plugins.
- The options are listed below in the Server Options section.
- To change the wording used in the pop-up interface, edit the /messages/messages.json file.
- When you run the index.php file in your browser, you should see a screen looking like this:
- After this is showing successfully, you will need to configure a front-end to run off this server, and change the ‘ajFeedback’ > ‘server’ parameter to the address shown at the bottom of the server’s home-page.
- You can then install (or develop) plugins to the system.
Server Options
Staging: To ensure you are set to the staging version of the settings, set the ‘usingStaging’ param to ‘true’.
To test the web domain, use the following small PHP script:
<?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
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
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.
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
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
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
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.
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).
(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:
sudo crontab -e
*/1 * * * * /usr/bin/nodejs /yourserverpath/node/sentiment.js -production -labelregexp ^api1db ssl: Makes the connection to the database encrypted. Ver >= 1.9.5
"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
db ssl key: The file path of the server’s key file. Ver >= 1.9.5
db ssl cert: The file path of the server’s certificate file. Ver >= 1.9.5
db ssl cacert: The file path of the CA Certificate file. Ver >= 1.9.5
db ssl capath: The path to the folder that contains the CA Certificate file. Ver >= 1.9.5
db ssl protocol: A list of the supported ssl protocols (separated by semi-colons). Ver >= 1.9.5. Here are some common protocols:
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
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. Ver >= 2.7.0
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 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 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 vendor amazonAWS: optional. This is for S3 storage of uploaded images. You will need an Amazon ‘accessKey’, ‘secretKey’ and ‘imageURL’, in this case.
uploads resizeVideo url en es: optional. This link appears on the Upload page, and allows for users to resize their video via an external website. The text “[LANG]” in the URL will be replaced with the user’s current language code. There is a translation from the AtomJump language codes to an external website’s language codes.
uploads recordAudio url en es: optional. This link appears on the Upload page, and allows for users to record an audio clip via an external website. The text “[LANG]” in the URL will be replaced with the user’s current language code. There is a translation from the AtomJump language codes to an external website’s language codes. Installations with the live audio “recording” option available, may find this link largely redundant, but it is particularly useful for sites on http on e.g. a LAN, which can’t use the live audio recording feature.
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"
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.
recording supported types video audio photo: This feature allows selective switching off and on of the immediate recording of media messages. On the interface this appears as a red circle alongside the comment input box, when supported is set to ‘true’. For live video and audio recordings, you are ideally on an “https” server (the camera feature will work without an https server, but audio and video need it). You will need to install “ffmpg” for audio and video translations (see the Recommended Installation Steps, above).
video url privateUrl domain privateDomain totalVideoServers langCodeInnerVsOuter totalVideoServersUrl hostHttps: The video provider url can be different for forums without a password entry (‘url’) vs those with a password to enter (‘privateUrl’). The URL can have the parameters [FORUM] [LANG] [SERVERID] replaced with their numerical equivalents to form the final URL. SERVERID is there for large scalability of server URLs for e.g. https://jitsi32.atomjump.com where ’32’ would be the server id. The ‘domain’ versions (‘domain’ and ‘privateDomain’), are for the embedded software to function. ‘langCodeInnerVsOuter’ does a translation from AtomJump language codes, to the video forum language codes. ‘hostHttps’ set to ‘true’ gives you a full embedded video interface, while ‘false’ only links to the remote video service (which would be opened in it’s own SSL server URL).
If you are using a remote set of Jitsi servers to your own server, and it is running an AtomJump Messaging server itself, you can set this URL, ‘totalVideoServersUrl’ to e.g. “https://your-atomjump-server/path/vid-server-cnt.php”. Then you can set up a daily cron job on your own server to ensure you are using a random server from the pool of Jitsi servers available, remotely. To set this cronjob:
sudo crontab -e # Add the line e.g. 0 0 * * * /usr/bin/php /var/www/html/your-atomjump-api/update-vid-server-cnt.php
To ensure you keep the most recent Jitsi embedding Javascript software cached on your AtomJump Messaging Server, set up this hourly crontab:
sudo crontab -e # Add the line e.g. 0 0 * * * /usr/bin/php /var/www/html/your-atomjump-api/get-latest-vid-js.php
You can add Jitsi-specific video conferencing options to both the public forums (‘jitsiPublicOptions’) and AtomJump private password-protected forums (‘jitsiPrivateOptions’). More information can be found on these options at https://jitsi.github.io/handbook/docs/dev-guide/dev-guide-iframe/. Some of these options/constraints may already be imposed by the Jitsi hosting provider at the server end. These options apply in addition, on the client end. You can also potentially add options to the ‘url’ / ‘privateUrl’ at the end of the URL itself (see the Jitsi documentation for further details), for altering the link version of the URL.
Changing language packs
Please see the /config/language-packs/README.md file for instructions on changing which languages are available to your users.
Contributing
Contributions are welcome, and they can take the shape of:
- 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.
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.
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).
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.