+TABLE OF CONTENTS
+=================
+* Prerequisites
+ - PHP modules
+ - Better performance
+* Installation
+ - Getting it up and running
+ - Fancy URLs
+ - Sphinx
+ - SMS
+ - Queues and daemons
+ - Themes
+ - Translation
+ - Backups
+ - Private
+
Prerequisites
=============
+PHP modules
+-----------
+
The following software packages are *required* for this software to
run correctly.
-- PHP 5.3.2+ For newer versions, some functions that are used may be
+- PHP 5.4+ For newer versions, some functions that are used may be
disabled by default, such as the pcntl_* family. See the
section on 'Queues and daemons' for more information.
-- MariaDB 5.x GNU Social uses, by default, a MariaDB server for data
+- 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.x.
+ 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)
Your PHP installation must include the following PHP extensions for a
functional setup of GNU Social:
-- Curl Fetching files by HTTP.
-- XMLWriter For formatting XML and HTML output.
-- mysqlnd The native driver for PHP5 MariaDB connections. If you
- use MySQL, 'mysql' or 'mysqli' may work.
-- GD Image manipulation (scaling).
-- mbstring For handling Unicode (UTF-8) encoded strings.
-- bcmath or gmp For Salmon signatures (part of OStatus)
+- 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-json For WebFinger lookups and more.
+- php5-mysqlnd The native driver for PHP5 MariaDB connections. If you
+ use MySQL, 'mysql' or 'mysqli' may work.
+
+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:
-- memcache A client for the memcached server, which caches database
- information in volatile memory. This is important for
- adequate performance on high-traffic sites. You will
- also need a memcached server to store the data in.
+- 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
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 install
-a PHP bytecode cache/accelerator. Currently the recommended cache module
-is 'xcache', which after installation (php5-xcache) can be enabled in
-your site's config.php with:
-
- addPlugin('XCache');
-
-External libraries
-------------------
-
-A number of external PHP libraries are used to provide basic
-functionality and optional functionality for your system. For your
-convenience, they are available in the "extlib" directory of this
-package, and you do not have to download and install them. However,
-you may want to keep them up-to-date with the latest upstream version,
-and the URLs are listed here for your convenience.
-
-- DB_DataObject http://pear.php.net/package/DB_DataObject
-- Validate http://pear.php.net/package/Validate
-- OpenID by Janrain, http://janrain.com/openid-enabled/
-- PEAR DB. Although this is an older data access system (new
- packages should use PDO), the OpenID libraries depend on PEAR DB
- or MDB2.
-- OAuth.php from http://oauth.googlecode.com/svn/code/php/
-- markdown.php from http://michelf.com/projects/php-markdown/
-- PEAR Mail, for sending out mail notifications
- http://pear.php.net/package/Mail
-- PEAR Net_SMTP, if you use the SMTP factory for notifications
- http://pear.php.net/package/Net_SMTP
-- PEAR Net_Socket, if you use the SMTP factory for notifications
- http://pear.php.net/package/Net_Socket
-- XMPPHP, the follow-up to Class.Jabber.php. Probably the best XMPP
- library available for PHP. http://xmpphp.googlecode.com/. Note that
- as of this writing the version of this library that is available in
- the extlib directory is *significantly different* from the upstream
- version (patches have been submitted). Upgrading to the upstream
- version may render your StatusNet site unable to send or receive XMPP
- messages.
-- Facebook library. Used for the Facebook application.
-- PEAR Validate is used for URL and email validation.
-- Console_GetOpt for parsing command-line options.
- predecessor to OStatus.
-- HTTP_Request2, a library for making HTTP requests.
-- PEAR Net_URL2 is an HTTP_Request2 dependency.
-
-A design goal of GNU Social is that the basic Web functionality should
-work on even the most restrictive commercial hosting services.
-However, additional functionality, such as receiving messages by XMPP,
-require that you be able to run long-running processes on your account.
-In addition, posting by email require that you be able to install a mail
-filter in your mail server.
+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, it is documented there together with its settings.
Installation
============
+Getting it up and running
+-------------------------
+
Installing the basic GNU Social web component is relatively easy,
especially if you've previously installed PHP/MariaDB packages.
$config['mail']['domain'] = 'yourdomain.example.net';
-At this point, post-by-email and post-by-SMS-gateway should work. Note
-that if your mail server is on a different computer from your email
-server, you'll need to have a full installation of StatusNet, a working
-config.php, and access to the StatusNet database from the mail server.
-
-XMPP
-----
-
-XMPP (eXtended Message and Presence Protocol, <http://xmpp.org/>) is the
-instant-messenger protocol that drives Jabber and GTalk IM. You can
-distribute messages via XMPP using the system below; however, you
-need to run the XMPP incoming daemon to allow incoming messages as
-well.
-
-1. You may want to strongly consider setting up your own XMPP server.
- Ejabberd, OpenFire, and JabberD are all Open Source servers.
- Jabber, Inc. provides a high-performance commercial server.
-
-2. You must register a Jabber ID (JID) with your new server. It helps
- to choose a name like "update@example.com" or "notice" or something
- similar. Alternately, your "update JID" can be registered on a
- publicly-available XMPP service, like jabber.org or GTalk.
-
- StatusNet will not register the JID with your chosen XMPP server;
- you need to do this manually, with an XMPP client like Gajim,
- Telepathy, or Pidgin.im.
-
-3. Configure your site's XMPP variables, as described below in the
- configuration section.
-
-On a default installation, your site can broadcast messages using
-XMPP. Users won't be able to post messages using XMPP unless you've
-got the XMPP daemon running. See 'Queues and daemons' below for how
-to set that up. Also, once you have a sizable number of users, sending
-a lot of SMS, OStatus, and XMPP messages whenever someone posts a message
-can really slow down your site; it may cause posting to timeout.
-
-NOTE: stream_select(), a crucial function for network programming, is
-broken on PHP 5.2.x less than 5.2.6 on amd64-based servers. We don't
-work around this bug in StatusNet; current recommendation is to move
-off of amd64 to another server.
-
-Public feed
------------
-
-You can send *all* messages from your social networking site to a
-third-party service using XMPP. This can be useful for providing
-search, indexing, bridging, or other cool services.
-
-To configure a downstream site to receive your public stream, add
-their "JID" (Jabber ID) to your config.php as follows:
- $config['xmpp']['public'][] = 'downstream@example.net';
-
-(Don't miss those square brackets at the end.) Note that your XMPP
-broadcasting must be configured as mentioned above. Although you can
-send out messages at "Web time", high-volume sites should strongly
-consider setting up queues and daemons.
Queues and daemons
------------------
Some activities that StatusNet needs to do, like broadcast OStatus, SMS,
-and XMPP messages, can be 'queued' and done by off-line bots instead.
-For this to work, 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.
+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
+job 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).
+
+Each time it can, 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.
server!), set the following variable:
$config['queue']['enabled'] = true;
+ $config['queue']['daemon'] = true;
You may also want to look at the 'daemon' section of this file for
more daemon options. Note that if you set the 'user' and/or 'group'
* 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)
-* other daemons that you may have enabled
+* 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
following files:
display.css: a CSS2 file for "default" styling for all browsers.
-ie6.css: a CSS2 file for override styling for fixing up Internet
- Explorer 6.
-ie7.css: a CSS2 file for override styling for fixing up Internet
- Explorer 7.
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.
projects / quix0rs-gnu-social.git / blobdiff