8fbdb4b9ac
Internationalization support is required for transliteration, which is currently used when creating the slugs for hashtags and such. It is a much more stable and efficient solution than having an unmaintainable list of unciode characters in an array...
470 lines
17 KiB
Plaintext
470 lines
17 KiB
Plaintext
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.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+ 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, '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:
|
|
|
|
- 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, 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.
|
|
|
|
1. Unpack the tarball you downloaded on your Web server. Usually a
|
|
command like this will work:
|
|
|
|
tar zxf gnusocial-*.tar.gz
|
|
|
|
...which will make a gnusocial-x.y.z 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. Move the tarball to a directory of your choosing in your Web root
|
|
directory. Usually something like this will work:
|
|
|
|
mv gnusocial-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 "Fancy URL" support, which you can read more about if you
|
|
scroll down a bit in this document.
|
|
|
|
3. Make your target directory writeable by the Web server.
|
|
|
|
chmod a+w /var/www/gnusocial/
|
|
|
|
On some systems, this will probably work:
|
|
|
|
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, background, and
|
|
file subdirectories writeable by the Web server. An insecure way to do
|
|
this is:
|
|
|
|
chmod a+w /var/www/gnusocial/avatar
|
|
chmod a+w /var/www/gnusocial/background
|
|
chmod a+w /var/www/gnusocial/file
|
|
|
|
You can also make the avatar, background, and file directories
|
|
writeable by the Web server group, as noted above.
|
|
|
|
5. Create a database to hold your site data. Something like this
|
|
should work:
|
|
|
|
mysqladmin -u "root" --password="rootpassword" create gnusocial
|
|
|
|
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 gnusocial.*
|
|
TO 'gnusocial'@'localhost'
|
|
IDENTIFIED BY 'agoodpassword';
|
|
|
|
You should change the user identifier 'gnusocial' 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:
|
|
|
|
http://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 user, post some notices, edit your profile, etc.
|
|
|
|
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:
|
|
|
|
http://example.net/gnusocial/index.php/gnusocial/fred
|
|
|
|
On certain systems that don't support this kind of syntax, they'll
|
|
look like this:
|
|
|
|
http://example.net/gnusocial/index.php?p=gnusocial/fred
|
|
|
|
It's possible to configure the software so it looks like this instead:
|
|
|
|
http://example.net/gnusocial/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. Copy the htaccess.sample file to .htaccess in your StatusNet
|
|
directory.
|
|
|
|
2. Change the "RewriteBase" in the new .htaccess file to be the URL path
|
|
to your GNU Social installation on your server. Typically this will
|
|
be the path to your GNU Social directory relative to your Web root.
|
|
If you are installing it in the root directory, leave it as '/'.
|
|
|
|
3. Add, uncomment or change a line in your config.php file so it says:
|
|
|
|
$config['site']['fancy'] = true;
|
|
|
|
You should now be able to navigate to a "fancy" URL on your server,
|
|
like:
|
|
|
|
http://example.net/gnusocial/main/register
|
|
|
|
If you changed your HTTP server configuration, you may need to restart
|
|
the server first.
|
|
|
|
If it doesn't work, double-check that AllowOverride for the GNU Social
|
|
directory is 'All' in your Apache configuration file. This is usually
|
|
/etc/httpd.conf, /etc/apache/httpd.conf, or (on Debian and Ubuntu)
|
|
/etc/apache2/sites-available/default. See the Apache documentation for
|
|
.htaccess files for more details:
|
|
|
|
http://httpd.apache.org/docs/2.2/howto/htaccess.html
|
|
|
|
Also, check that mod_rewrite is installed and enabled:
|
|
|
|
http://httpd.apache.org/docs/2.2/mod/mod_rewrite.html
|
|
|
|
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.
|
|
|
|
2. Edit /etc/aliases on your mail server and add the following line:
|
|
|
|
*: /path/to/statusnet/scripts/maildaemon.php
|
|
|
|
3. 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.
|
|
|
|
4. Set the following in your config.php file:
|
|
|
|
$config['mail']['domain'] = 'yourdomain.example.net';
|
|
|
|
|
|
|
|
Queues and daemons
|
|
------------------
|
|
|
|
Some activities that StatusNet 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
|
|
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.
|
|
|
|
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 StatusNet
|
|
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 (both the Web server and the queues
|
|
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'
|
|
options, you'll need to create that user and/or group by hand.
|
|
They're not created automatically.
|
|
|
|
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)
|
|
* 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.
|
|
|
|
Themes
|
|
------
|
|
|
|
Older themes (version 0.9.x and below) no longer work with StatusNet
|
|
1.0.x, due to major changes in the site layout. We ship with three new
|
|
themes for this version, 'neo', 'neo-blue' and 'neo-light'.
|
|
|
|
As of right now, your ability to change the theme is site-wide; users
|
|
can't choose their own theme. Additionally, the only thing you can
|
|
change in the theme is CSS stylesheets and some image files; you can't
|
|
change the HTML output, like adding or removing menu items.
|
|
|
|
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.
|
|
|
|
Translation
|
|
-----------
|
|
|
|
Translations in StatusNet use the gettext system <http://www.gnu.org/software/gettext/>.
|
|
Theoretically, you can add your own sub-directory to the locale/
|
|
subdirectory to add a new language to your system. You'll need to
|
|
compile the ".po" files into ".mo" files, however.
|
|
|
|
Contributions of translation information to StatusNet are very easy:
|
|
you can use the Web interface at translatewiki.net to add one
|
|
or a few or lots of new translations -- or even new languages. You can
|
|
also download more up-to-date .po files there, if you so desire.
|
|
|
|
For info on helping with translations, see http://status.net/wiki/Translations
|
|
|
|
Backups
|
|
-------
|
|
|
|
There is no built-in system for doing backups in StatusNet. You can make
|
|
backups of a working StatusNet system by backing up the database and
|
|
the Web directory. To backup the database use mysqldump <http://ur1.ca/7xo>
|
|
and to backup the Web directory, try tar.
|
|
|
|
Private
|
|
-------
|
|
|
|
The administrator can set the "private" flag for a site so that it's
|
|
not visible to non-logged-in users. (This is the default for new installs of version 1.0!)
|
|
|
|
This might be useful for workgroups who want to share a social
|
|
networking site for project management, but host it on a public
|
|
server.
|
|
|
|
Total privacy is attempted but not guaranteed or ensured. Private sites
|
|
currently don't work well with OStatus federation.
|
|
|
|
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. Usually a command like this will work:
|
|
|
|
mkdir /var/www/statusnet-files
|
|
|
|
2. Make the file uploads directory writeable by the web server. An
|
|
insecure way to do this is:
|
|
|
|
chmod a+x /var/www/statusnet-files
|
|
|
|
3. Tell StatusNet to use this directory for file uploads. Add a line
|
|
like this to your config.php:
|
|
|
|
$config['attachments']['dir'] = '/var/www/statusnet-files';
|