From 49c01141048749123f02d240c8048faa252f94b7 Mon Sep 17 00:00:00 2001 From: John Kristensen Date: Sun, 6 Mar 2016 01:50:52 +1100 Subject: [PATCH] Initial port of admin manual to Sphinx A port of the existing admin manual over to reStructuredText and using Sphinx to generate the documentation to see if it would be a suitable replacement for the existing php generated method. --- docs/admin/backing_up_and_restoring.rst | 95 +++++ docs/admin/contributing.rst | 17 + docs/admin/index.rst | 14 + docs/admin/installing_gnu_social.rst | 474 +++++++++++++++++++++ docs/admin/protocol_overview.rst | 4 + docs/admin/upgrading_your_installation.rst | 120 ++++++ docs/admin/using_queue_daemons.rst | 103 +++++ docs/index.rst | 1 + 8 files changed, 828 insertions(+) create mode 100644 docs/admin/backing_up_and_restoring.rst create mode 100644 docs/admin/contributing.rst create mode 100644 docs/admin/index.rst create mode 100644 docs/admin/installing_gnu_social.rst create mode 100644 docs/admin/protocol_overview.rst create mode 100644 docs/admin/upgrading_your_installation.rst create mode 100644 docs/admin/using_queue_daemons.rst diff --git a/docs/admin/backing_up_and_restoring.rst b/docs/admin/backing_up_and_restoring.rst new file mode 100644 index 0000000..d451ac2 --- /dev/null +++ b/docs/admin/backing_up_and_restoring.rst @@ -0,0 +1,95 @@ +Backing Up and Restoring +======================== + +Backing Up +---------- +It is important to back up GNU social regularly. If you need to revert to an +old backup you will lose any newer notices. Any follows that happened since +then will result in mismatched information on your server and remote servers. + +You should also back up immediately prior to any upgrade. This is especially +important if you are following the *nightly* branch where serious bugs might +slip through. + +There are two parts to your GNU social installation and they most *both* be +backed up at the same time. + +1. The files hosted by your webserver. This is a mixture of GNU social code and + user data. This a directory probably located somewhere like + ``/var/www/social``. + +2. The contents of the MariaDB/MySQL database. + +Web Files +^^^^^^^^^ +You don't need to do anything fancy. Just make sure you have a copy of the +folder. If you're using a commercial web hosting service there is probably a +button you can press to download an archive of all your files. Note that this +normally does *not* include your database. + +If you have shell access on the server, assuming the GNU social folder is +located at ``/var/www/social``, you can make a compressed backup in your home +directory like this:: + + TIMESTAMP=$(date +%Y%m%d-%H%M) + cd /var/www + tar -Jcf "~/$TIMESTAMP-social-www.tar.xz" --exclude=.git social + +If you are serving files straight out of the git repository this will back up +only the currently checked out copy, not the entire history. (Using a git +repository this way is not recommended as you may cause chaos in your database +if you accidentally check out the wrong thing.) + +Database +^^^^^^^^ +There are many different tools and techniques for backing up MySQL databases. +If you're using a commercial web hosting service there will probably be +somewhere in the web interface where you can download a copy of the GNU social +database. + +If you have shell access the simplest way to create a backup is using the tool +*mysqldump*. :: + + TIMESTAMP=$(date +%Y%m%d-%H%M) + mysqldump -u "database_username" -p "database_name" | xz -c - > "~/$TIMESTAMP-social.sql.xz" + +You will be prompted for a password. Type in the password for the MySQL user. + + +Restoring from a Backup +----------------------- +1. Stop the queue daemons if they're running. + +2. Restore the web files. + +3. Restore the database. + +4. Restart the queue daemons. + +If you followed the examples above you might type the following:: + + cd /var/www/social + + # Stop the daemons + bash ./scripts/stopdaemons.sh + + # Delete and restore the web files + rm -r * + cd .. + tar -Jxf ~/20160130-1200-social-www.tar.xz + + # Recreate the database (using MySQL root account) + mysqladmin -u root -p drop social + mysqladmin -u root -p create social + mysql -u root -p social + + # Inside mysql client + GRANT ALL on social.* TO 'social'@'localhost' IDENTIFIED BY 'the_old_password'; + exit + + # Restore the database as the GNU social MySQL user + xzcat ~/20160130-1200-social.sql.xz | mysql -u social -p social + + # Restart the queue daemons + cd social + bash ./scripts/startdaemons.sh diff --git a/docs/admin/contributing.rst b/docs/admin/contributing.rst new file mode 100644 index 0000000..a024471 --- /dev/null +++ b/docs/admin/contributing.rst @@ -0,0 +1,17 @@ +Contributing +============ + +Translations +------------ +For info on helping with translations, see the `platform currently in use`_ for +translations.gettext system. If you for some reason do not wish to sign up to +the Transifex service, you can review the files in the ``locale/`` +sub-directory of GNU social. Each plugin also has its own translation files. + +.. _platform currently in use: https://www.transifex.com/projects/p/gnu-social/ + +To get your own site to use all the translated languages, and you are tracking +the git repo, you will need to install at least 'gettext' on your system and +then run:: + + $ make translations diff --git a/docs/admin/index.rst b/docs/admin/index.rst new file mode 100644 index 0000000..7b8f707 --- /dev/null +++ b/docs/admin/index.rst @@ -0,0 +1,14 @@ +Admin Manual +============ + +Contents: + +.. toctree:: + :maxdepth: 2 + + installing_gnu_social + using_queue_daemons + backing_up_and_restoring + upgrading_your_installation + protocol_overview + contributing diff --git a/docs/admin/installing_gnu_social.rst b/docs/admin/installing_gnu_social.rst new file mode 100644 index 0000000..6a72ec0 --- /dev/null +++ b/docs/admin/installing_gnu_social.rst @@ -0,0 +1,474 @@ +Installing GNU social +===================== + +Prerequisites +------------- + +Selecting a branch +^^^^^^^^^^^^^^^^^^ +GNU social has three different branches of development offering a range of +choices between stability and the latest features. + +1.2.x + This is the current stable release. The code has been tested for a while. + +master + ``master`` receives more frequent updates and is usually working well. + +nightly + ``nightly`` gets updated the most but is not always working. + +When you download the source code in :ref:`getting-it-up-and-running` you will +need to know which branch you want to install. You can always move to a more +unstable branch but going backwards is not guaranteed to work. + +If you want to use `Qvitter`_ — that's the plugin that makes GNU social look +like Twitter — be aware that it is tested against GNU social nightly. If you +are using a different branch and having problems with that plugin try upgrading +to nightly. + +Web server configuration +^^^^^^^^^^^^^^^^^^^^^^^^ +You should use HTTPS to encrypt all communications with your GNU social +instance. Until recently it cost money to get a trusted certificate but now the +Let's Encrypt project enables you to `obtain a trusted certificate at no +cost`_. + +If you are thinking about starting with HTTP and setting up encryption later, +don't do that. You may have problems if you start with HTTP and later move to +HTTPS. + +If you want to use Qvitter be aware that it only supports installations that +are installed directly on the domain. That is, the URL to access GNU social +needs to be ``https://www.some.domain/`` and not +``https://www.some.domain/gnusocial/``. It also requires you to have Fancy URLs +enabled. If you're using apache that means you need mod_rewrite and the ability +to use ``.htaccess`` files. + +PHP modules +^^^^^^^^^^^ +The following software packages are *required* for this software to run +correctly. + +PHP 5.5+ + For newer versions, some functions that are used may be disabled by default, + such as the ``pcntl_*`` family. See the section on + :doc:`using_queue_daemons`. + +.. todo:: remove italics from Using Queue Daemons link + +MariaDB 5+ + GNU Social uses, by default, a MariaDB server for data storage. Versions 5.x + and 10.x have both reportedly worked well. It is also possible to run MySQL + 5.5+. + +Web server + Apache, lighttpd and nginx will all work. CGI mode is recommended and also + some variant of 'suexec' (or a proper setup php-fpm pool) + NOTE: mod_rewrite or its equivalent is extremely useful. + +Your PHP installation must include the following PHP extensions for a +functional setup of GNU social: + +openssl + (compiled in for Debian, enabled manually in Arch Linux) + +php5-curl + Fetching files by HTTP. + +php5-gd + Image manipulation (scaling). + +php5-gmp + For Salmon signatures (part of OStatus). + +php5-intl + Internationalization support (transliteration et al). + +php5-json + For WebFinger lookups and more. + +php5-mysqlnd + The native driver for PHP5 MariaDB connections. If you use MySQL, + ``php5-mysql`` or ``php5-mysqli`` may be enough. + +The above package names are for Debian based systems. In the case of Arch +Linux, PHP is compiled with support for most extensions but they require manual +enabling in the relevant ``php.ini`` file (mostly ``php5-gmp``). + +Better performance +^^^^^^^^^^^^^^^^^^ +For some functionality, you will also need the following extensions: + +opcache + Improves performance a lot. Included in PHP, must be enabled manually in + ``php.ini`` for most distributions. Find and set at least: + ``opcache.enable=1`` + +mailparse + Efficient parsing of email requires this extension. Submission by email or + SMS-over-email uses this. + +sphinx + A client for the sphinx server, an alternative to MySQL or Postgresql + fulltext search. You will also need a Sphinx server to serve the search + queries. + +gettext + For multiple languages. Default on many PHP installs; will be emulated if not + present. + +exif + For thumbnails to be properly oriented. + +You may also experience better performance from your site if you configure a +PHP cache/accelerator. Most distributions come with "opcache" support. Enable +it in your ``php.ini`` where it is documented together with its settings. + + +Installation +------------ +.. _getting-it-up-and-running: + +Getting it up and running +^^^^^^^^^^^^^^^^^^^^^^^^^ +Installing the basic GNU Social web component is relatively easy, especially if +you've previously installed PHP/MariaDB packages. + +1. The source code is distributed using a git repository `on GNU's Gitlab + server`_. There are two ways to download it: + + * Use `git`_ on your own computer to clone the repository. Once it is + on your computer it is easy to download incremental updates. + + * Download a zip or tarball from Gitlab's web interface. This way you won't + need git but you will need to download the whole thing every time you + update. + + If you want to use git, run the following command. It will download the + whole repository and place it in a folder called gnusocial. + + ``git clone https://git.gnu.io/gnu/gnu-social.git gnusocial`` + + Then select the branch you wish to use:: + + cd gnusocial + git checkout master # or '1.2.x' or 'nightly' + + If you would like to download it directly instead, go to the `1.2.x`_, + `master`_ or `nightly`_ branch on the Gitlab web page. In the top-right + corner there is a button to download a zip file containing that branch. If + you press the drop-down arrow on the right you can access different types of + archive. + +.. todo:: code block the links + +.. image:: ../../resources/admin/tree_download.png + :alt: Download button on gitlab + :align: center + +.. _1.2.x: https://git.gnu.io/gnu/gnu-social/tree/1.2.x +.. _master: https://git.gnu.io/gnu/gnu-social/tree/master +.. _nightly: https://git.gnu.io/gnu/gnu-social/tree/nightly + + Unpack the tarball you downloaded on your Web server. Usually a command like + this will work:: + + tar zxf gnu-social-*.tar.gz + + ...which will make a subdirectory in your current directory. (If you don't + have shell access on your Web server, you may have to unpack the tarball on + your local computer and FTP the files to the server.) + +2. Whichever way you downloaded GNU social, move the files to a directory of + your choosing in your Web root directory. Usually something like this will + work: + + For a git repository:: + + cd gnusocial + mkdir /var/www/gnusocial + cp -rv * /var/www/gnusocial + + For a downloaded tarball:: + + mv gnu-social-x.y.z /var/www/gnusocial + + This will often make your GNU Social instance available in the ``gnusocial`` + path of your server, like ``http://example.net/gnusocial``. "social" or + "blog" might also be good path names. If you know how to configure virtual + hosts on your web server, you can try setting up + ``http://social.example.net/`` or the like. + + If you have "rewrite" support on your webserver, and you should, then please + enable this in order to make full use of your site. This will enable + :ref:`fancy-urls` support. + +3. Make your target directory writeable by the Web server, please note however + that will give all users write access and securing the webserver is not + within the scope of this document. :: + + chmod a+w /var/www/gnusocial/ + + On some systems, this will work as a more secure alternative:: + + chgrp www-data /var/www/gnusocial/ + chmod g+w /var/www/gnusocial/ + + If your Web server runs as another user besides ``www-data``, try that user's + default group instead. As a last resort, you can create a new group like + ``gnusocial`` and add the web server's user to the group. + +4. You should also take this moment to make your ``avatar`` and ``file`` + sub-directories writeable by the Web server. The insecure way to do this + is:: + + chmod a+w /var/www/gnusocial/avatar + chmod a+w /var/www/gnusocial/file + + You can also make the avatar, and file directories just writable by the web + server group, as noted above. + +5. Create a database to hold your site data. Something like this should work + (you will be prompted for your database password):: + + mysqladmin -u "root" -p create socia + + Note that GNU social should have its own database; you should not share the + database with another program. You can name it whatever you want, though. + + (If you don't have shell access to your server, you may need to use a tool + like phpMyAdmin to create a database. Check your hosting service's + documentation for how to create a new MariaDB database.) + +6. Create a new database account that GNU social will use to access the + database. If you have shell access, this will probably work from the MariaDB + shell:: + + GRANT ALL on social.* + TO 'social'@'localhost' + IDENTIFIED BY 'agoodpassword'; + + You should change the user identifier ``social`` and ``agoodpassword`` to + your preferred new database username and password. You may want to test + logging in to MariaDB as this new user. + +7. In a browser, navigate to the GNU Social install script; something like:: + + https://social.example.net/install.php + + Enter the database connection information and your site name. The install + program will configure your site and install the initial, almost-empty + database. + +8. You should now be able to navigate to your social site's main directory and + see the "Public Timeline", which will probably be empty. You can now + register new users, post some notices, edit your profile, etc. + +.. _fancy-urls: + +Fancy URLs +^^^^^^^^^^ +By default, GNU Social will use URLs that include the main PHP program's name +in them. For example, a user's home profile might be found at either of these +URLS depending on the webserver's configuration and capabilities:: + + https://social.example.net/index.php/fred + https://social.example.net/index.php?p=fred + +It's possible to configure the software to use fancy URLs so it looks like this +instead:: + + https://social.example.net/fred + +These "fancy URLs" are more readable and memorable for users. To use fancy +URLs, you must either have Apache 2.x with ``.htaccess`` enabled and +mod_rewrite enabled, OR know how to configure "url redirection" in your server +(like lighttpd or nginx). + +1. See the instructions for each respective webserver software: + + * For Apache, inspect the ``htaccess.sample`` file and save it as + ``.htaccess`` after making any necessary modifications. Our sample file is + well commented. + + * For lighttpd, inspect the lighttpd.conf.example file and apply the + appropriate changes in your virtualhost configuration for lighttpd. + + * For nginx, inspect the ``nginx.conf.sample`` file and apply the appropriate + changes. + + * For other webservers, we gladly accept contributions of server + configuration examples. + +2. Assuming your webserver is properly configured and have its settings applied + (remember to reload/restart it), you can add this to your GNU social's + ``config.php`` file:: + + $config['site']['fancy'] = true; + +You should now be able to navigate to a "fancy" URL on your server, like:: + + https://social.example.net/main/register + +Themes +^^^^^^ +As of right now, your ability change the theme is limited to CSS stylesheets +and some image files; you can't change the HTML output, like adding or removing +menu items, without the help of a plugin. + +You can choose a theme using the ``$config['site']['theme']`` element in the +``config.php`` file. See below for details. + +You can add your own theme by making a sub-directory of the 'theme' +subdirectory with the name of your theme. Each theme can have the following +files: + +display.css + a CSS2 file for "default" styling for all browsers. + +logo.png + a logo image for the site. + +default-avatar-profile.png + a 96x96 pixel image to use as the avatar for users who don't upload their + own. + +default-avatar-stream.png + Ditto, but 48x48. For streams of notices. + +default-avatar-mini.png + Ditto ditto, but 24x24. For subscriptions listing on profile pages. + +You may want to start by copying the files from the default theme to your own +directory. + +Private +^^^^^^^ +A GNU social node can be configured as "private", which means it will not +federate with other nodes in the network. It is not a recommended method of +using GNU social and we cannot at the current state of development guarantee +that there are no leaks (what a public network sees as features, private sites +will likely see as bugs). + +Private nodes are however an easy way to easily setup collaboration and image +sharing within a workgroup or a smaller community where federation is not a +desired feature. Also, it is possible to change this setting and instantly gain +full federation features. + +Access to file attachments can also be restricted to logged-in users only: + +1. Add a directory outside the web root where your file uploads will be stored. + Use this command as an initial guideline to create it:: + + mkdir /var/www/gnusocial-files + +2. Make the file uploads directory writeable by the web server. An insecure way + to do this is (to do it properly, read up on UNIX file permissions and + configure your webserver accordingly):: + + chmod a+x /var/www/gnusocial-files + +3. Tell GNU social to use this directory for file uploads. Add a line like this + to your ``config.php``:: + + $config['attachments']['dir'] = '/var/www/gnusocial-files'; + +Extra features +-------------- + +Sphinx +^^^^^^ +To use a Sphinx server to search users and notices, you'll need to enable the +SphinxSearch plugin. Add to your ``config.php``:: + + addPlugin('SphinxSearch'); + $config['sphinx']['server'] = 'searchhost.local'; + +You also need to install, compile and enable the sphinx pecl extension for php +on the client side, which itself depends on the sphinx development files. + +See ``plugins/SphinxSearch/README`` for more details and server setup. + +SMS +^^^ +StatusNet supports a cheap-and-dirty system for sending update messages to +mobile phones and for receiving updates from the mobile. Instead of sending +through the SMS network itself, which is costly and requires buy-in from the +wireless carriers, it simply piggybacks on the email gateways that many +carriers provide to their customers. So, SMS configuration is essentially email +configuration. + +Each user sends to a made-up email address, which they keep a secret. Incoming +email that is "From" the user's SMS email address, and "To" the users' secret +email address on the site's domain, will be converted to a notice and stored in +the DB. + +For this to work, there *must* be a domain or sub-domain for which all (or +most) incoming email can pass through the incoming mail filter. + +1. Run the SQL script ``carrier.sql`` in your StatusNet database. This will + usually work:: + + mysql -u "statusnetuser" --password="statusnetpassword" statusnet < db/carrier.sql + + This will populate your database with a list of wireless carriers that + support email SMS gateways. + +2. Make sure the maildaemon.php file is executable:: + + chmod +x scripts/maildaemon.php + + Note that "daemon" is kind of a misnomer here; the script is more of a filter + than a daemon. + +3. Edit ``/etc/aliases`` on your mail server and add the following line:: + + *: /path/to/statusnet/scripts/maildaemon.php + +4. Run whatever code you need to to update your aliases database. For many mail + servers (Postfix, Exim, Sendmail), this should work:: + + newaliases + + You may need to restart your mail server for the new database to take effect. + +5. Set the following in your ``config.php`` file:: + + $config['mail']['domain'] = 'yourdomain.example.net'; + + + +After installation +------------------ + +Run queue daemons +^^^^^^^^^^^^^^^^^ +By default GNU social tries to do regular work such as communicating with +remote servers while it is handling HTTP requests for users. This is often +insufficient. If possible you should run the queue daemons. Please refer to +this section: :doc:`using_queue_daemons`. + +.. todo:: remove italics from Using Queue Daemons link + +Backups +^^^^^^^ +There is no built-in system for doing backups in GNU social. You can make +backups of a working system by backing up the database and the Web directory. +To backup the database use `mysqldump`_ and to backup the Web directory, try +tar. + +.. _mysqldump: https://mariadb.com/kb/en/mariadb/mysqldump/ + +Upgrading +^^^^^^^^^ +Upgrading is strongly recommended to stay up to date with security fixes and +new features. For instructions on how to upgrade GNU social code, please refer +to this section: :doc:`upgrading_your_installation`. + +.. todo:: remove italics from Upgrading Your Installation link + +.. _Qvitter: https://git.gnu.io/h2p/Qvitter +.. _obtain a trusted certificate at no cost: https://letsencrypt.org/howitworks/ +.. _on GNU's Gitlab server: https://git.gnu.io/gnu/gnu-social +.. _git: https://git-scm.com/ diff --git a/docs/admin/protocol_overview.rst b/docs/admin/protocol_overview.rst new file mode 100644 index 0000000..252ef07 --- /dev/null +++ b/docs/admin/protocol_overview.rst @@ -0,0 +1,4 @@ +Protocol Overview +================= +GNU social runs primarily on voodoo magic. If anybody knows better please +advise. diff --git a/docs/admin/upgrading_your_installation.rst b/docs/admin/upgrading_your_installation.rst new file mode 100644 index 0000000..38f1820 --- /dev/null +++ b/docs/admin/upgrading_your_installation.rst @@ -0,0 +1,120 @@ +Upgrading Your Installation +=========================== + +Nightly or GNU social 1.1.x to GNU social 1.2.x +----------------------------------------------- +If you are tracking the GNU social git repository, we currently recommend using +the "master" branch (or nightly if you want to use latest features) and follow +this procedure: + +1. Back up your data. The StatusNet upgrade discussions below have some + guidelines to back up the database and files (mysqldump and rsync). + +2. Stop your queue daemons (you can run this command even if you do not use the + queue daemons):: + + $ bash scripts/stopdaemons.sh + +3. Run the command to fetch the latest sourcecode:: + + $ git pull + + If you are not using git we recommend following the instructions below for + upgrading "StatusNet 1.1.x to GNU social 1.2.x" as they are similar. + +4. Run the upgrade script:: + + $ php scripts/upgrade.php + + The upgrade script will likely take a long time because it will upgrade the + tables to another character encoding and make other automated upgrades. Make + sure it ends without errors. If you get errors, create a new issue on the + `GNU social project page`_. + +.. _GNU social project page: https://git.gnu.io/gnu/gnu-social/issues + +5. Start your queue daemons again (you can run this command even if you do not + use the queue daemons):: + + $ bash scripts/startdaemons.sh + +6. Report any issues at https://git.gnu.io/gnu/gnu-social/issues + +If you are using ssh keys to log in to your server, you can make this procedure +pretty painless (assuming you have automated backups already). Make sure you +"cd" into the correct directory (in this case "htdocs") and use the correct +login@hostname combo:: + + ssh social@domain.example 'cd htdocs \ + && bash scripts/stopdaemons.sh \ + && git pull \ + && time php scripts/upgrade.php \ + && bash \ + scripts/startdaemons.sh' + +.. todo:: remove href from login@hostname + + +StatusNet 1.1.x to GNU social 1.2.x +----------------------------------- +We cannot support migrating from any other version of StatusNet than 1.1.1. If +you are running a StatusNet version lower than this, please follow the upgrade +procedures for each respective StatusNet version. + +You are now running StatusNet 1.1.1 and want to migrate to GNU social 1.2.x. +Beware there may be changes in minimum required version of PHP and the modules +required, so review the INSTALL file (php5-intl is a newly added dependency for +example). + +**Before you begin: Make backups**. Always make backups. Of your entire +directory structure and the database too. All tables. All data. Alles. + +1. Make a backup of everything. To backup the database, you can use a variant + of this command (you will be prompted for the database password):: + + $ mysqldump -u dbuser -p dbname > social-backup.sql + +2. Stop your queue daemons. :: + + $ bash scripts/stopdaemons.sh + + Not everyone runs queue daemons, but the above command won't hurt. + +3. Unpack your GNU social code to a fresh directory. You can do this by cloning + our git repository:: + + $ git clone https://git.gnu.io/gnu/gnu-social.git gnusocial + +4. Synchronize your local files to the GNU social directory. These will be the + local files such as avatars, config and files: + + * ``avatar/*`` + * ``file/*`` + * ``local/*`` + * ``.htaccess`` + * ``config.php`` + + This command will point you in the right direction on how to do it:: + + $ rsync -avP statusnet/{.htaccess,avatar,file,local,config.php} gnusocial/ + +5. Replace your old StatusNet directory with the new GNU social directory in + your webserver root. + +6. Run the upgrade script:: + + $ php scripts/upgrade.php + + The upgrade script will likely take a long time because it will upgrade the + tables to another character encoding and make other automated upgrades. Make + sure it ends without errors. If you get errors, create a new issue on the + `GNU social project page`_. + +.. _GNU social project page: https://git.gnu.io/gnu/gnu-social/issues + +7. Start your queue daemons:: + + $ bash scripts/startdaemons.sh + +8. Report any issues at https://git.gnu.io/gnu/gnu-social/issues + diff --git a/docs/admin/using_queue_daemons.rst b/docs/admin/using_queue_daemons.rst new file mode 100644 index 0000000..c526e1a --- /dev/null +++ b/docs/admin/using_queue_daemons.rst @@ -0,0 +1,103 @@ +Using Queue Daemons +=================== + +Queues and Daemons +------------------ +Some activities that GNU social needs to do, like broadcast OStatus, SMS, XMPP +messages and TwitterBridge operations, can be 'queued' and done by off-line +bots instead. + +Two mechanisms are available to achieve offline operations: + +* New embedded OpportunisticQM plugin, which is enabled by default + +* Legacy queuedaemon script, which can be enabled via config file. + +OpportunisticQM plugin +^^^^^^^^^^^^^^^^^^^^^^ +This plugin is enabled by default. It tries its best to do background jobs +during regular HTTP requests, like API or HTML pages calls. + +Since queueing system is enabled by default, notices to be broadcasted will be +stored, by default, into DB (table ``queue_item``). + +Whenever it has time, OpportunisticQM will try to handle some of them. + +This is a good solution whether you: + +* have no access to command line (shared hosting) + +* do not want to deal with long-running PHP processes + +* run a low traffic GNU social instance + +In other case, you really should consider enabling the queuedaemon for +performance reasons. Background daemons are necessary anyway if you wish to use +the Instant Messaging features such as communicating via XMPP. + +queuedaemon +^^^^^^^^^^^ +If you want to use legacy queuedaemon, you must be able to run long-running +offline processes, either on your main Web server or on another server you +control. (Your other server will still need all the above prerequisites, with +the exception of Apache.) Installing on a separate server is probably a good +idea for high-volume sites. + +1. You'll need the "CLI" (command-line interface) version of PHP installed on + whatever server you use. + + Modern PHP versions in some operating systems have disabled functions related + to forking, which is required for daemons to operate. To make this work, make + sure that your php-cli config (``/etc/php5/cli/php.ini``) does NOT have these + functions listed under 'disable_functions': + + * pcntl_fork, pcntl_wait, pcntl_wifexited, pcntl_wexitstatus, + pcntl_wifsignaled, pcntl_wtermsig + + Other recommended settings for optimal performance are: + + * ``mysqli.allow_persistent = On`` + * ``mysqli.reconnect = On`` + +2. If you're using a separate server for queues, install GNU social somewhere + on the server. You don't need to worry about the ``.htaccess`` file, but + make sure that your ``config.php`` file is close to, or identical to, your + Web server's version. + +3. In your config.php files (on the server where you run the queue daemon), set + the following variable:: + + $config['queue']['daemon'] = true; + +4. On the queues server, run the command ``scripts/startdaemons.sh``. + + This will run the queue handlers: + + queuedaemon.php + polls for queued items for inbox processing and pushing out to OStatus, + SMS, XMPP, etc. + + imdaemon.php + if an IM plugin is enabled (like XMPP) + + (plugins) + other daemons, like TwitterBridge ones, that you may have enabled + + These daemons will automatically restart in most cases of failure including + memory leaks (if a memory_limit is set), but may still die or behave oddly if + they lose connections to the XMPP or queue servers. + + It may be a good idea to use a daemon-monitoring service, like 'monit', to + check their status and keep them running. + + All the daemons write their process IDs (pids) to ``/var/run/`` by default. + This can be useful for starting, stopping, and monitoring the daemons. If you + are running multiple sites on the same machine, it will be necessary to avoid + collisions of these PID files by setting a site-specific directory in + ``config.php``:: + + $config['daemon']['piddir'] = __DIR__ . '/../run/'; + + It is also possible to use a STOMP server instead of our kind of hacky + home-grown DB-based queue solution. This is strongly recommended for best + response time, especially when using XMPP. diff --git a/docs/index.rst b/docs/index.rst index 81b91ff..fe91dd9 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -12,6 +12,7 @@ Contents: :maxdepth: 2 user/index + admin/index