X-Git-Url: https://git.mxchange.org/?a=blobdiff_plain;f=INSTALL;h=0483320a78bc08795afbde082346043a583d37a9;hb=261ccfac8699534ff584a2f93d5dcd384529d855;hp=bac8d3400504fca8b93466575e0e196b1ee25bb9;hpb=e2c50d202fba2e953dc3798091bdb2858ab8a8ab;p=quix0rs-gnu-social.git diff --git a/INSTALL b/INSTALL index bac8d34005..0483320a78 100644 --- a/INSTALL +++ b/INSTALL @@ -1,15 +1,34 @@ +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) @@ -18,23 +37,26 @@ run correctly. 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 @@ -42,62 +64,18 @@ For some functionality, you will also need the following extensions: 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. @@ -305,75 +283,47 @@ For this to work, there *must* be a domain or sub-domain for which all $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, ) 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. @@ -399,6 +349,7 @@ server is probably a good idea for high-volume sites. 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' @@ -412,7 +363,7 @@ 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) -* 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 @@ -453,10 +404,6 @@ 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. -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.