forked from GNUsocial/gnu-social
1710 lines
69 KiB
Plaintext
1710 lines
69 KiB
Plaintext
------
|
|
README
|
|
------
|
|
|
|
StatusNet 0.8.2 ("Life and How to Live It")
|
|
1 Nov 2009
|
|
|
|
This is the README file for StatusNet (formerly Laconica), the Open
|
|
Source microblogging platform. It includes installation instructions,
|
|
descriptions of options you can set, warnings, tips, and general info
|
|
for administrators. Information on using StatusNet can be found in the
|
|
"doc" subdirectory or in the "help" section on-line.
|
|
|
|
About
|
|
=====
|
|
|
|
StatusNet (formerly Laconica) is a Free and Open Source microblogging
|
|
platform. It helps people in a community, company or group to exchange
|
|
short (140 character) messages over the Web. Users can choose which
|
|
people to "follow" and receive only their friends' or colleagues'
|
|
status messages. It provides a similar service to sites like Twitter,
|
|
Jaiku, Yammer, and Plurk.
|
|
|
|
With a little work, status messages can be sent to mobile phones,
|
|
instant messenger programs (GTalk/Jabber), and specially-designed
|
|
desktop clients that support the Twitter API.
|
|
|
|
StatusNet supports an open standard called OpenMicroBlogging
|
|
<http://openmicroblogging.org/> that lets users on different Web sites
|
|
or in different companies subscribe to each others' notices. It
|
|
enables a distributed social network spread all across the Web.
|
|
|
|
StatusNet was originally developed for the Open Software Service,
|
|
Identi.ca <http://identi.ca/>. It is shared with you in hope that you
|
|
too make an Open Software Service available to your users. To learn
|
|
more, please see the Open Software Service Definition 1.1:
|
|
|
|
http://www.opendefinition.org/ossd
|
|
|
|
StatusNet, Inc. <http://status.net/> also offers this software as a
|
|
Web service, requiring no installation on your part. The software run
|
|
on status.net is identical to the software available for download, so
|
|
you can move back and forth between a hosted version or a version
|
|
installed on your own servers.
|
|
|
|
License
|
|
=======
|
|
|
|
This program is free software: you can redistribute it and/or modify
|
|
it under the terms of the GNU Affero General Public License as
|
|
published by the Free Software Foundation, either version 3 of the
|
|
License, or (at your option) any later version.
|
|
|
|
This program is distributed in the hope that it will be useful, but
|
|
WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
|
Affero General Public License for more details.
|
|
|
|
You should have received a copy of the GNU Affero General Public
|
|
License along with this program, in the file "COPYING". If not, see
|
|
<http://www.gnu.org/licenses/>.
|
|
|
|
IMPORTANT NOTE: The GNU Affero General Public License (AGPL) has
|
|
*different requirements* from the "regular" GPL. In particular, if
|
|
you make modifications to the StatusNet source code on your server,
|
|
you *MUST MAKE AVAILABLE* the modified version of the source code
|
|
to your users under the same license. This is a legal requirement
|
|
of using the software, and if you do not wish to share your
|
|
modifications, *YOU MAY NOT INSTALL STATUSNET*.
|
|
|
|
Additional library software has been made available in the 'extlib'
|
|
directory. All of it is Free Software and can be distributed under
|
|
liberal terms, but those terms may differ in detail from the AGPL's
|
|
particulars. See each package's license file in the extlib directory
|
|
for additional terms.
|
|
|
|
New this version
|
|
================
|
|
|
|
This is a minor feature and bugfix release since version 0.8.1,
|
|
released Aug 26 2009. Notable changes this version:
|
|
|
|
- New script for deleting user accounts. Not particularly safe or
|
|
community-friendly. Better for deleting abusive accounts than for
|
|
users who are 'retiring'.
|
|
- Improved detection of URLs in notices, specifically for punctuation
|
|
chars like ~, :, $, _, -, +, !, @, and %.
|
|
- Removed some extra <dl> semantic HTML code.
|
|
- Correct error in status-network database ini file (having multiple
|
|
statusnet sites with a single codebase)
|
|
- Fixed error output for Twitter posting failures.
|
|
- Fixed bug in Twitter queue handler that requeued inapplicable
|
|
notices ad infinitum.
|
|
- Improve FOAF output for remote users.
|
|
- new commands to join and leave groups.
|
|
- Fixed bug in which you cannot turn off importing friends timelines
|
|
flag.
|
|
- Better error handling in Twitter posting.
|
|
- Show oEmbed data for XHTML files as well as plain HTML.
|
|
- Updated bug database link in README.
|
|
- require HTML tidy extension.
|
|
- add support for HTTP Basic Auth in PHP CGI or FastCGI (e.g. GoDaddy).
|
|
- autofocus input to selected entry elements depending on page.
|
|
- updated layout for filter-by-tag form.
|
|
- better layout for inbox and outbox pages.
|
|
- fix highlighting search terms in attributes of notice list elements.
|
|
- Correctly handle errors in linkback plugin.
|
|
- Updated biz theme.
|
|
- Updated cloudy theme.
|
|
- Don't match '::' as an IPv6 address.
|
|
- Use the same decision logic for deciding whether to mark an
|
|
attachment as an enclosure in RSS or as a paperclip item in Web
|
|
output.
|
|
- Fixed a bug in the Piwik plugin that hard-coded the site ID.
|
|
- Add a param, inreplyto, to notice/new to allow an explicit response
|
|
to another notice.
|
|
- Show username in subject of emails.
|
|
- Check if avatar exists before trying to delete it.
|
|
- Correctly add omb_version to response for request token in OMB.
|
|
- Add a few more SMS carriers.
|
|
- Add a few more notice sources.
|
|
- Vary: header.
|
|
- Improvements to the AutoCompletePlugin.
|
|
- Check for 'dl' before using it.
|
|
- Make it impossible to delete self-subscriptions via the API.
|
|
- Fix pagination of tagged user pages.
|
|
- Make PiwikAnalyticsPlugin work with addPlugin().
|
|
- Removed trailing single space in user nicknames in notice lists.
|
|
- Show context link if a notice starts a conversation.
|
|
- blacklist all files and directories in install dir.
|
|
- handle GoDaddy-style PATH_INFO, including script name.
|
|
- add home_timeline synonym for friends_timeline.
|
|
- Add a popup window for the realtime plugin.
|
|
- Add some more streams for the realtime plugin.
|
|
- Fix a bug that overwrote group creation timestamp on every edit.
|
|
- Moved HTTP error code strings to a class variable.
|
|
- The Twitter API now returns server errors in the correct format.
|
|
- Reset the doctype for HTML output.
|
|
- Fixed a number of notices.
|
|
- Don't show search suggestions for private sites.
|
|
- Some corrections to FBConnect nav overrides.
|
|
- Slightly less database-intensive session management.
|
|
- Updated name of software in installer script.
|
|
- Include long-form attachment URLs if url-shortener is disabled.
|
|
- Include updated localisations for Polish, Greek, Hebrew, Icelandic,
|
|
Norwegian, and Chinese.
|
|
- Include upstream fixes to gettext.php.
|
|
- Correct for regression in Facebook API for updates.
|
|
- Ignore "Sent from my iPhone" (and similar) in mail updates.
|
|
- Use the NICKNAME_FMT constant for detecting nicknames.
|
|
- Check for site servername config'd.
|
|
- Compatibility fix for empty status updates with Twitter API.
|
|
- Option to show files privately (EXPERIMENTAL! Use with caution.)
|
|
|
|
Prerequisites
|
|
=============
|
|
|
|
The following software packages are *required* for this software to
|
|
run correctly.
|
|
|
|
- PHP 5.2.3+. It may be possible to run this software on earlier
|
|
versions of PHP, but many of the functions used are only available
|
|
in PHP 5.2 or above.
|
|
- MySQL 5.x. The StatusNet database is stored, by default, in a MySQL
|
|
server. It has been primarily tested on 5.x servers, although it may
|
|
be possible to install on earlier (or later!) versions. The server
|
|
*must* support the MyISAM storage engine -- the default for most
|
|
MySQL servers -- *and* the InnoDB storage engine.
|
|
- A Web server. Preferably, you should have Apache 2.2.x with the
|
|
mod_rewrite extension installed and enabled.
|
|
|
|
Your PHP installation must include the following PHP extensions:
|
|
|
|
- Curl. This is for fetching files by HTTP.
|
|
- XMLWriter. This is for formatting XML and HTML output.
|
|
- MySQL. For accessing the database.
|
|
- GD. For scaling down avatar images.
|
|
- mbstring. For handling Unicode (UTF-8) encoded strings.
|
|
- gettext. For multiple languages. Default on many PHP installs.
|
|
- tidy. Used to clean up HTML/URLs for the URL shortener to consume.
|
|
|
|
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.
|
|
- Mailparse. Efficient parsing of email requires this extension.
|
|
Submission by email or SMS-over-email uses this extension.
|
|
- Sphinx Search. 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.
|
|
|
|
You will almost definitely get 2-3 times better performance from your
|
|
site if you install a PHP bytecode cache/accelerator. Some well-known
|
|
examples are: eaccelerator, Turck mmcache, xcache, apc. Zend Optimizer
|
|
is a proprietary accelerator installed on some hosting sites.
|
|
|
|
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 from OpenIDEnabled (not the PEAR version!). We decided
|
|
to use the openidenabled.com version since it's more widely
|
|
implemented, and seems to be better supported.
|
|
http://openidenabled.com/php-openid/
|
|
- PEAR DB. Although this is an older data access system (new
|
|
packages should probably use PHP DBO), the OpenID libraries
|
|
depend on PEAR DB so we use it here, too. DB_DataObject can
|
|
also use PEAR MDB2, which may give you better performance
|
|
but won't work with OpenID.
|
|
http://pear.php.net/package/DB
|
|
- 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 Services_oEmbed. Used for some multimedia integration.
|
|
- PEAR HTTP_Request is an oEmbed dependency.
|
|
- PEAR Validate is an oEmbed dependency.
|
|
- PEAR Net_URL2 is an oEmbed dependency.
|
|
- Console_GetOpt for parsing command-line options.
|
|
|
|
A design goal of StatusNet is that the basic Web functionality should
|
|
work on even the most restrictive commercial hosting services.
|
|
However, additional functionality, such as receiving messages by
|
|
Jabber/GTalk, require that you be able to run long-running processes
|
|
on your account. In addition, posting by email or from SMS require
|
|
that you be able to install a mail filter in your mail server.
|
|
|
|
Installation
|
|
============
|
|
|
|
Installing the basic StatusNet Web component is relatively easy,
|
|
especially if you've previously installed PHP/MySQL packages.
|
|
|
|
1. Unpack the tarball you downloaded on your Web server. Usually a
|
|
command like this will work:
|
|
|
|
tar zxf statusnet-0.8.2.tar.gz
|
|
|
|
...which will make a statusnet-0.8.2 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 statusnet-0.8.2 /var/www/mublog
|
|
|
|
This will make your StatusNet instance available in the mublog path of
|
|
your server, like "http://example.net/mublog". "microblog" or
|
|
"statusnet" might also be good path names. If you know how to
|
|
configure virtual hosts on your web server, you can try setting up
|
|
"http://micro.example.net/" or the like.
|
|
|
|
3. Make your target directory writeable by the Web server.
|
|
|
|
chmod a+w /var/www/mublog/
|
|
|
|
On some systems, this will probably work:
|
|
|
|
chgrp www-data /var/www/mublog/
|
|
chmod g+w /var/www/mublog/
|
|
|
|
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 "mublog" 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/mublog/avatar
|
|
chmod a+w /var/www/mublog/background
|
|
chmod a+w /var/www/mublog/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 microblog data. Something like this
|
|
should work:
|
|
|
|
mysqladmin -u "username" --password="password" create statusnet
|
|
|
|
Note that StatusNet must have its own database; you can't 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 PHPAdmin to create a database. Check your hosting
|
|
service's documentation for how to create a new MySQL database.)
|
|
|
|
6. Create a new database account that StatusNet will use to access the
|
|
database. If you have shell access, this will probably work from the
|
|
MySQL shell:
|
|
|
|
GRANT ALL on statusnet.*
|
|
TO 'lacuser'@'localhost'
|
|
IDENTIFIED BY 'lacpassword';
|
|
|
|
You should change 'lacuser' and 'lacpassword' to your preferred new
|
|
username and password. You may want to test logging in to MySQL as
|
|
this new user.
|
|
|
|
7. In a browser, navigate to the StatusNet install script; something like:
|
|
|
|
http://yourserver.example.com/mublog/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 microblog's main directory
|
|
and see the "Public Timeline", which will be empty. If not, magic
|
|
has happened! You can now register a new user, post some notices,
|
|
edit your profile, etc. However, you may want to wait to do that stuff
|
|
if you think you can set up "fancy URLs" (see below), since some
|
|
URLs are stored in the database.
|
|
|
|
Fancy URLs
|
|
----------
|
|
|
|
By default, StatusNet 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.org/mublog/index.php/mublog/fred
|
|
|
|
On certain systems that don't support this kind of syntax, they'll
|
|
look like this:
|
|
|
|
http://example.org/mublog/index.php?p=mublog/fred
|
|
|
|
It's possible to configure the software so it looks like this instead:
|
|
|
|
http://example.org/mublog/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_redirect enabled, -OR- know how to configure "url redirection" in
|
|
your server.
|
|
|
|
1. Copy the htaccess.sample file to .htaccess in your StatusNet
|
|
directory. Note: if you have control of your server's httpd.conf or
|
|
similar configuration files, it can greatly improve performance to
|
|
import the .htaccess file into your conf file instead. If you're
|
|
not sure how to do it, you may save yourself a lot of headache by
|
|
just leaving the .htaccess file.
|
|
|
|
2. Change the "RewriteBase" in the new .htaccess file to be the URL path
|
|
to your StatusNet installation on your server. Typically this will
|
|
be the path to your StatusNet directory relative to your Web root.
|
|
|
|
3. Add or 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/mublog/main/register
|
|
|
|
If you changed your HTTP server configuration, you may need to restart
|
|
the server first.
|
|
|
|
Sphinx
|
|
------
|
|
|
|
To use a Sphinx server to search users and notices, 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.
|
|
"pecl install sphinx" should take care of that. Add "extension=sphinx.so"
|
|
to your php.ini and reload apache to enable it.
|
|
|
|
You can update your MySQL or Postgresql databases to drop their fulltext
|
|
search indexes, since they're now provided by sphinx.
|
|
|
|
On the sphinx server side, a script reads the main database and build
|
|
the keyword index. A cron job reads the database and keeps the sphinx
|
|
indexes up to date. scripts/sphinx-cron.sh should be called by cron
|
|
every 5 minutes, for example. scripts/sphinx.sh is an init.d script
|
|
to start and stop the sphinx search daemon.
|
|
|
|
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 "lacuser" --password="lacpassword" 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';
|
|
|
|
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, OMB, 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 microblogging 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 OMB, 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.
|
|
|
|
1. You'll need the "CLI" (command-line interface) version of PHP
|
|
installed on whatever server you use.
|
|
|
|
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;
|
|
|
|
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. It
|
|
needs as a parameter the install path; if you run it from the
|
|
StatusNet dir, "." should suffice.
|
|
|
|
This will run eight (for now) queue handlers:
|
|
|
|
* xmppdaemon.php - listens for new XMPP messages from users and stores
|
|
them as notices in the database.
|
|
* jabberqueuehandler.php - sends queued notices in the database to
|
|
registered users who should receive them.
|
|
* publicqueuehandler.php - sends queued notices in the database to
|
|
public feed listeners.
|
|
* ombqueuehandler.php - sends queued notices to OpenMicroBlogging
|
|
recipients on foreign servers.
|
|
* smsqueuehandler.php - sends queued notices to SMS-over-email addresses
|
|
of registered users.
|
|
* xmppconfirmhandler.php - sends confirmation messages to registered
|
|
users.
|
|
* twitterqueuehandler.php - sends queued notices to Twitter for user
|
|
who have opted to set up Twitter bridging.
|
|
* facebookqueuehandler.php - sends queued notices to Facebook for users
|
|
of the built-in Facebook application.
|
|
|
|
Note that these queue daemons are pretty raw, and need your care. In
|
|
particular, they leak memory, and you may want to restart them on a
|
|
regular (daily or so) basis with a cron job. Also, if they lose
|
|
the connection to the XMPP server for too long, they'll simply die. 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.
|
|
|
|
Since version 0.8.0, it's now possible to use a STOMP server instead of
|
|
our kind of hacky home-grown DB-based queue solution. See the "queues"
|
|
config section below for how to configure to use STOMP. As of this
|
|
writing, the software has been tested with ActiveMQ (
|
|
|
|
Twitter Bridge
|
|
--------------
|
|
|
|
* OAuth
|
|
|
|
As of 0.8.1, OAuth is used to to access protected resources on Twitter
|
|
instead of HTTP Basic Auth. To use Twitter bridging you will need
|
|
to register your instance of StatusNet as an application on Twitter
|
|
(http://twitter.com/apps), and update the following variables in your
|
|
config.php with the consumer key and secret Twitter generates for you:
|
|
|
|
$config['twitter']['consumer_key'] = 'YOURKEY';
|
|
$config['twitter']['consumer_secret'] = 'YOURSECRET';
|
|
|
|
When registering your application with Twitter set the type to "Browser"
|
|
and your Callback URL to:
|
|
|
|
http://example.org/mublog/twitter/authorization
|
|
|
|
The default access type should be, "Read & Write".
|
|
|
|
* Importing statuses from Twitter
|
|
|
|
To allow your users to import their friends' Twitter statuses, you will
|
|
need to enable the bidirectional Twitter bridge in config.php:
|
|
|
|
$config['twitterbridge']['enabled'] = true;
|
|
|
|
and run the TwitterStatusFetcher daemon (scripts/twitterstatusfetcher.php).
|
|
Additionally, you will want to set the integration source variable,
|
|
which will keep notices posted to Twitter via StatusNet from looping
|
|
back. The integration source should be set to the name of your
|
|
application, exactly as you specified it on the settings page for your
|
|
StatusNet application on Twitter, e.g.:
|
|
|
|
$config['integration']['source'] = 'YourApp';
|
|
|
|
* Twitter Friends Syncing
|
|
|
|
Users may set a flag in their settings ("Subscribe to my Twitter friends
|
|
here" under the Twitter tab) to have StatusNet attempt to locate and
|
|
subscribe to "friends" (people they "follow") on Twitter who also have
|
|
accounts on your StatusNet system, and who have previously set up a link
|
|
for automatically posting notices to Twitter.
|
|
|
|
As of 0.8.0, this is no longer accomplished via a cron job. Instead you
|
|
must run the SyncTwitterFriends daemon (scripts/synctwitterfreinds.php).
|
|
|
|
Built-in Facebook Application
|
|
-----------------------------
|
|
|
|
StatusNet's Facebook application allows your users to automatically
|
|
update their Facebook statuses with their latest notices, invite
|
|
their friends to use the app (and thus your site), view their notice
|
|
timelines, and post notices -- all from within Facebook. The application
|
|
is built into StatusNet and runs on your host. For automatic Facebook
|
|
status updating to work you will need to enable queuing and run the
|
|
facebookqueuehandler.php daemon (see the "Queues and daemons" section
|
|
above).
|
|
|
|
Quick setup instructions*:
|
|
|
|
Install the Facebook Developer application on Facebook:
|
|
|
|
http://www.facebook.com/developers/
|
|
|
|
Use it to create a new application and generate an API key and secret.
|
|
Uncomment the Facebook app section of your config.php and copy in the
|
|
key and secret, e.g.:
|
|
|
|
# Config section for the built-in Facebook application
|
|
$config['facebook']['apikey'] = 'APIKEY';
|
|
$config['facebook']['secret'] = 'SECRET';
|
|
|
|
In Facebook's application editor, specify the following URLs for your app:
|
|
|
|
- Canvas Callback URL: http://example.net/mublog/facebook/
|
|
- Post-Remove Callback URL: http://example.net/mublog/facebook/remove
|
|
- Post-Add Redirect URL: http://apps.facebook.com/yourapp/
|
|
- Canvas Page URL: http://apps.facebook.com/yourapp/
|
|
|
|
(Replace 'example.net' with your host's URL, 'mublog' with the path
|
|
to your StatusNet installation, and 'yourapp' with the name of the
|
|
Facebook application you created.)
|
|
|
|
Additionally, Choose "Web" for Application type in the Advanced tab.
|
|
In the "Canvas setting" section, choose the "FBML" for Render Method,
|
|
"Smart Size" for IFrame size, and "Full width (760px)" for Canvas Width.
|
|
Everything else can be left with default values.
|
|
|
|
*For more detailed instructions please see the installation guide on the
|
|
StatusNet wiki:
|
|
|
|
http://status.net/trac/wiki/FacebookApplication
|
|
|
|
Sitemaps
|
|
--------
|
|
|
|
Sitemap files <http://sitemaps.org/> are a very nice way of telling
|
|
search engines and other interested bots what's available on your site
|
|
and what's changed recently. You can generate sitemap files for your
|
|
StatusNet instance.
|
|
|
|
1. Choose your sitemap URL layout. StatusNet creates a number of
|
|
sitemap XML files for different parts of your site. You may want to
|
|
put these in a sub-directory of your StatusNet directory to avoid
|
|
clutter. The sitemap index file tells the search engines and other
|
|
bots where to find all the sitemap files; it *must* be in the main
|
|
installation directory or higher. Both types of file must be
|
|
available through HTTP.
|
|
|
|
2. To generate your sitemaps, run the following command on your server:
|
|
|
|
php scripts/sitemap.php -f index-file-path -d sitemap-directory -u URL-prefix-for-sitemaps
|
|
|
|
Here, index-file-path is the full path to the sitemap index file,
|
|
like './sitemapindex.xml'. sitemap-directory is the directory where
|
|
you want the sitemaps stored, like './sitemaps/' (make sure the dir
|
|
exists). URL-prefix-for-sitemaps is the full URL for the sitemap dir,
|
|
typically something like <http://example.net/mublog/sitemaps/>.
|
|
|
|
You can use several methods for submitting your sitemap index to
|
|
search engines to get your site indexed. One is to add a line like the
|
|
following to your robots.txt file:
|
|
|
|
Sitemap: /mublog/sitemapindex.xml
|
|
|
|
This is a good idea for letting *all* Web spiders know about your
|
|
sitemap. You can also submit sitemap files to major search engines
|
|
using their respective "Webmaster centres"; see sitemaps.org for links
|
|
to these resources.
|
|
|
|
Themes
|
|
------
|
|
|
|
There are two themes shipped with this version of StatusNet: "identica",
|
|
which is what the Identi.ca site uses, and "default", which is a good
|
|
basis for other sites.
|
|
|
|
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.
|
|
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.
|
|
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.
|
|
|
|
NOTE: the HTML generated by StatusNet changed *radically* between
|
|
version 0.6.x and 0.7.x. Older themes will need signification
|
|
modification to use the new output format.
|
|
|
|
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 http://status.net/pootle/ 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.
|
|
|
|
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 might be useful for
|
|
workgroups who want to share a microblogging site for project
|
|
management, but host it on a public server.
|
|
|
|
Note that this is an experimental feature; total privacy is not
|
|
guaranteed or ensured. Also, privacy is all-or-nothing for a site; you
|
|
can't have some accounts or notices private, and others public.
|
|
Finally, the interaction of private sites with OpenMicroBlogging is
|
|
undefined. Remote users won't be able to subscribe to users on a
|
|
private site, but users of the private site may be able to subscribe
|
|
to users on a remote site. (Or not... it's not well tested.) The
|
|
"proper behaviour" hasn't been defined here, so handle with care.
|
|
|
|
Upgrading
|
|
=========
|
|
|
|
IMPORTANT NOTE: StatusNet 0.7.4 introduced a fix for some
|
|
incorrectly-stored international characters ("UTF-8"). For new
|
|
installations, it will now store non-ASCII characters correctly.
|
|
However, older installations will have the incorrect storage, and will
|
|
consequently show up "wrong" in browsers. See below for how to deal
|
|
with this situation.
|
|
|
|
If you've been using StatusNet 0.7, 0.6, 0.5 or lower, or if you've
|
|
been tracking the "git" version of the software, you will probably
|
|
want to upgrade and keep your existing data. There is no automated
|
|
upgrade procedure in StatusNet 0.8.2. Try these step-by-step
|
|
instructions; read to the end first before trying them.
|
|
|
|
0. Download StatusNet and set up all the prerequisites as if you were
|
|
doing a new install.
|
|
1. Make backups of both your database and your Web directory. UNDER NO
|
|
CIRCUMSTANCES should you try to do an upgrade without a known-good
|
|
backup. You have been warned.
|
|
2. Shut down Web access to your site, either by turning off your Web
|
|
server or by redirecting all pages to a "sorry, under maintenance"
|
|
page.
|
|
3. Shut down XMPP access to your site, typically by shutting down the
|
|
xmppdaemon.php process and all other daemons that you're running.
|
|
If you've got "monit" or "cron" automatically restarting your
|
|
daemons, make sure to turn that off, too.
|
|
4. Shut down SMS and email access to your site. The easy way to do
|
|
this is to comment out the line piping incoming email to your
|
|
maildaemon.php file, and running something like "newaliases".
|
|
5. Once all writing processes to your site are turned off, make a
|
|
final backup of the Web directory and database.
|
|
6. Move your StatusNet directory to a backup spot, like "mublog.bak".
|
|
7. Unpack your StatusNet 0.8.2 tarball and move it to "mublog" or
|
|
wherever your code used to be.
|
|
8. Copy the config.php file and avatar directory from your old
|
|
directory to your new directory.
|
|
9. Copy htaccess.sample to .htaccess in the new directory. Change the
|
|
RewriteBase to use the correct path.
|
|
10. Rebuild the database. (You can safely skip this step and go to #12
|
|
if you're upgrading from another 0.8.x version).
|
|
|
|
NOTE: this step is destructive and cannot be
|
|
reversed. YOU CAN EASILY DESTROY YOUR SITE WITH THIS STEP. Don't
|
|
do it without a known-good backup!
|
|
|
|
If your database is at version 0.7.4, you can run a special upgrade
|
|
script:
|
|
|
|
mysql -u<rootuser> -p<rootpassword> <database> db/074to080.sql
|
|
|
|
Otherwise, go to your StatusNet directory and AFTER YOU MAKE A
|
|
BACKUP run the rebuilddb.sh script like this:
|
|
|
|
./scripts/rebuilddb.sh rootuser rootpassword database db/statusnet.sql
|
|
|
|
Here, rootuser and rootpassword are the username and password for a
|
|
user who can drop and create databases as well as tables; typically
|
|
that's _not_ the user StatusNet runs as. Note that rebuilddb.sh drops
|
|
your database and rebuilds it; if there is an error you have no
|
|
database. Make sure you have a backup.
|
|
For PostgreSQL databases there is an equivalent, rebuilddb_psql.sh,
|
|
which operates slightly differently. Read the documentation in that
|
|
script before running it.
|
|
11. Use mysql or psql client to log into your database and make sure that
|
|
the notice, user, profile, subscription etc. tables are non-empty.
|
|
12. Turn back on the Web server, and check that things still work.
|
|
13. Turn back on XMPP bots and email maildaemon. Note that the XMPP
|
|
bots have changed since version 0.5; see above for details.
|
|
|
|
If you're upgrading from very old versions, you may want to look at
|
|
the fixup_* scripts in the scripts directories. These will store some
|
|
precooked data in the DB. All upgraders should check out the inboxes
|
|
options below.
|
|
|
|
NOTE: the database definition file, laconica.ini, has been renamed to
|
|
statusnet.ini (since this is the recommended database name). If you
|
|
have a line in your config.php pointing to the old name, you'll need
|
|
to update it.
|
|
|
|
Notice inboxes
|
|
--------------
|
|
|
|
Before version 0.6.2, the page showing all notices from people the
|
|
user is subscribed to ("so-and-so with friends") was calculated at run
|
|
time. Starting with 0.6.2, we have a new data structure for holding a
|
|
user's "notice inbox". (Note: distinct from the "message inbox", which
|
|
is the "inbox" tab in the UI. The notice inbox appears under the
|
|
"Personal" tab.)
|
|
|
|
Notices are added to the inbox when they're created. This speeds up
|
|
the query considerably, and also allows us the opportunity, in the
|
|
future, to add different kind of notices to an inbox -- like @-replies
|
|
or subscriptions to search terms or hashtags.
|
|
|
|
Notice inboxes are enabled by default for new installations. If you
|
|
are upgrading an existing site, this means that your users will see
|
|
empty "Personal" pages. The following steps will help you fix the
|
|
problem.
|
|
|
|
0. $config['inboxes']['enabled'] can be set to one of three values. If
|
|
you set it to 'false', the site will work as before. Support for this
|
|
will probably be dropped in future versions.
|
|
1. Setting the flag to 'transitional' means that you're in transition.
|
|
In this mode, the code will run the "new query" or the "old query"
|
|
based on whether the user's inbox has been updated.
|
|
2. After setting the flag to "transitional", you can run the
|
|
fixup_inboxes.php script to create the inboxes. You may want to set
|
|
the memory limit high. You can re-run it without ill effect.
|
|
3. When fixup_inboxes is finished, you can set the enabled flag to
|
|
'true'.
|
|
|
|
NOTE: As of version 0.8.1 notice inboxes are automatically trimmed back
|
|
to ~1000 notices every once in a while.
|
|
|
|
NOTE: we will drop support for non-inboxed sites in the 0.9.x version
|
|
of StatusNet. It's time to switch now!
|
|
|
|
UTF-8 Database
|
|
--------------
|
|
|
|
StatusNet 0.7.4 introduced a fix for some incorrectly-stored
|
|
international characters ("UTF-8"). This fix is not
|
|
backwards-compatible; installations from before 0.7.4 will show
|
|
non-ASCII characters of old notices incorrectly. This section explains
|
|
what to do.
|
|
|
|
0. You can disable the new behaviour by setting the 'db''utf8' config
|
|
option to "false". You should only do this until you're ready to
|
|
convert your DB to the new format.
|
|
1. When you're ready to convert, you can run the fixup_utf8.php script
|
|
in the scripts/ subdirectory. If you've had the "new behaviour"
|
|
enabled (probably a good idea), you can give the ID of the first
|
|
"new" notice as a parameter, and only notices before that one will
|
|
be converted. Notices are converted in reverse chronological order,
|
|
so the most recent (and visible) ones will be converted first. The
|
|
script should work whether or not you have the 'db''utf8' config
|
|
option enabled.
|
|
2. When you're ready, set $config['db']['utf8'] to true, so that
|
|
new notices will be stored correctly.
|
|
|
|
Configuration options
|
|
=====================
|
|
|
|
The main configuration file for StatusNet (excepting configurations for
|
|
dependency software) is config.php in your StatusNet directory. If you
|
|
edit any other file in the directory, like lib/common.php (where most
|
|
of the defaults are defined), you will lose your configuration options
|
|
in any upgrade, and you will wish that you had been more careful.
|
|
|
|
Starting with version 0.7.1, you can put config files in the
|
|
/etc/statusnet/ directory on your server, if it exists. Config files
|
|
will be included in this order:
|
|
|
|
* /etc/statusnet/statusnet.php - server-wide config
|
|
* /etc/statusnet/<servername>.php - for a virtual host
|
|
* /etc/statusnet/<servername>_<pathname>.php - for a path
|
|
* INSTALLDIR/config.php - for a particular implementation
|
|
|
|
Almost all configuration options are made through a two-dimensional
|
|
associative array, cleverly named $config. A typical configuration
|
|
line will be:
|
|
|
|
$config['section']['option'] = value;
|
|
|
|
For brevity, the following documentation describes each section and
|
|
option.
|
|
|
|
site
|
|
----
|
|
|
|
This section is a catch-all for site-wide variables.
|
|
|
|
name: the name of your site, like 'YourCompany Microblog'.
|
|
server: the server part of your site's URLs, like 'example.net'.
|
|
path: The path part of your site's URLs, like 'mublog' or ''
|
|
(installed in root).
|
|
fancy: whether or not your site uses fancy URLs (see Fancy URLs
|
|
section above). Default is false.
|
|
logfile: full path to a file for StatusNet to save logging
|
|
information to. You may want to use this if you don't have
|
|
access to syslog.
|
|
logdebug: whether to log additional debug info like backtraces on
|
|
hard errors. Default false.
|
|
locale_path: full path to the directory for locale data. Unless you
|
|
store all your locale data in one place, you probably
|
|
don't need to use this.
|
|
language: default language for your site. Defaults to US English.
|
|
languages: A list of languages supported on your site. Typically you'd
|
|
only change this if you wanted to disable support for one
|
|
or another language:
|
|
"unset($config['site']['languages']['de'])" will disable
|
|
support for German.
|
|
theme: Theme for your site (see Theme section). Two themes are
|
|
provided by default: 'default' and 'stoica' (the one used by
|
|
Identi.ca). It's appreciated if you don't use the 'stoica' theme
|
|
except as the basis for your own.
|
|
email: contact email address for your site. By default, it's extracted
|
|
from your Web server environment; you may want to customize it.
|
|
broughtbyurl: name of an organization or individual who provides the
|
|
service. Each page will include a link to this name in the
|
|
footer. A good way to link to the blog, forum, wiki,
|
|
corporate portal, or whoever is making the service available.
|
|
broughtby: text used for the "brought by" link.
|
|
timezone: default timezone for message display. Users can set their
|
|
own time zone. Defaults to 'UTC', which is a pretty good default.
|
|
closed: If set to 'true', will disallow registration on your site.
|
|
This is a cheap way to restrict accounts to only one
|
|
individual or group; just register the accounts you want on
|
|
the service, *then* set this variable to 'true'.
|
|
inviteonly: If set to 'true', will only allow registration if the user
|
|
was invited by an existing user.
|
|
openidonly: If set to 'true', will only allow registrations and logins
|
|
through OpenID.
|
|
private: If set to 'true', anonymous users will be redirected to the
|
|
'login' page. Also, API methods that normally require no
|
|
authentication will require it. Note that this does not turn
|
|
off registration; use 'closed' or 'inviteonly' for the
|
|
behaviour you want.
|
|
notice: A plain string that will appear on every page. A good place
|
|
to put introductory information about your service, or info about
|
|
upgrades and outages, or other community info. Any HTML will
|
|
be escaped.
|
|
logo: URL of an image file to use as the logo for the site. Overrides
|
|
the logo in the theme, if any.
|
|
ssl: Whether to use SSL and https:// URLs for some or all pages.
|
|
Possible values are 'always' (use it for all pages), 'never'
|
|
(don't use it for any pages), or 'sometimes' (use it for
|
|
sensitive pages that include passwords like login and registration,
|
|
but not for regular pages). Default to 'never'.
|
|
sslserver: use an alternate server name for SSL URLs, like
|
|
'secure.example.org'. You should be careful to set cookie
|
|
parameters correctly so that both the SSL server and the
|
|
"normal" server can access the session cookie and
|
|
preferably other cookies as well.
|
|
shorturllength: Length of URL at which URLs in a message exceeding 140
|
|
characters will be sent to the user's chosen
|
|
shortening service.
|
|
dupelimit: minimum time allowed for one person to say the same thing
|
|
twice. Default 60s. Anything lower is considered a user
|
|
or UI error.
|
|
|
|
db
|
|
--
|
|
|
|
This section is a reference to the configuration options for
|
|
DB_DataObject (see <http://ur1.ca/7xp>). The ones that you may want to
|
|
set are listed below for clarity.
|
|
|
|
database: a DSN (Data Source Name) for your StatusNet database. This is
|
|
in the format 'protocol://username:password@hostname/databasename',
|
|
where 'protocol' is 'mysql' or 'mysqli' (or possibly 'postgresql', if you
|
|
really know what you're doing), 'username' is the username,
|
|
'password' is the password, and etc.
|
|
ini_yourdbname: if your database is not named 'statusnet', you'll need
|
|
to set this to point to the location of the
|
|
statusnet.ini file. Note that the real name of your database
|
|
should go in there, not literally 'yourdbname'.
|
|
db_driver: You can try changing this to 'MDB2' to use the other driver
|
|
type for DB_DataObject, but note that it breaks the OpenID
|
|
libraries, which only support PEAR::DB.
|
|
debug: On a database error, you may get a message saying to set this
|
|
value to 5 to see debug messages in the browser. This breaks
|
|
just about all pages, and will also expose the username and
|
|
password
|
|
quote_identifiers: Set this to true if you're using postgresql.
|
|
type: either 'mysql' or 'postgresql' (used for some bits of
|
|
database-type-specific SQL in the code). Defaults to mysql.
|
|
mirror: you can set this to an array of DSNs, like the above
|
|
'database' value. If it's set, certain read-only actions will
|
|
use a random value out of this array for the database, rather
|
|
than the one in 'database' (actually, 'database' is overwritten).
|
|
You can offload a busy DB server by setting up MySQL replication
|
|
and adding the slaves to this array. Note that if you want some
|
|
requests to go to the 'database' (master) server, you'll need
|
|
to include it in this array, too.
|
|
utf8: whether to talk to the database in UTF-8 mode. This is the default
|
|
with new installations, but older sites may want to turn it off
|
|
until they get their databases fixed up. See "UTF-8 database"
|
|
above for details.
|
|
|
|
syslog
|
|
------
|
|
|
|
By default, StatusNet sites log error messages to the syslog facility.
|
|
(You can override this using the 'logfile' parameter described above).
|
|
|
|
appname: The name that StatusNet uses to log messages. By default it's
|
|
"statusnet", but if you have more than one installation on the
|
|
server, you may want to change the name for each instance so
|
|
you can track log messages more easily.
|
|
priority: level to log at. Currently ignored.
|
|
facility: what syslog facility to used. Defaults to LOG_USER, only
|
|
reset if you know what syslog is and have a good reason
|
|
to change it.
|
|
|
|
queue
|
|
-----
|
|
|
|
You can configure the software to queue time-consuming tasks, like
|
|
sending out SMS email or XMPP messages, for off-line processing. See
|
|
'Queues and daemons' above for how to set this up.
|
|
|
|
enabled: Whether to uses queues. Defaults to false.
|
|
subsystem: Which kind of queueserver to use. Values include "db" for
|
|
our hacked-together database queuing (no other server
|
|
required) and "stomp" for a stomp server.
|
|
stomp_server: "broker URI" for stomp server. Something like
|
|
"tcp://hostname:61613". More complicated ones are
|
|
possible; see your stomp server's documentation for
|
|
details.
|
|
queue_basename: a root name to use for queues (stomp only). Typically
|
|
something like '/queue/sitename/' makes sense.
|
|
stomp_username: username for connecting to the stomp server; defaults
|
|
to null.
|
|
stomp_password: password for connecting to the stomp server; defaults
|
|
to null.
|
|
license
|
|
-------
|
|
|
|
The default license to use for your users notices. The default is the
|
|
Creative Commons Attribution 3.0 license, which is probably the right
|
|
choice for any public site. Note that some other servers will not
|
|
accept notices if you apply a stricter license than this.
|
|
|
|
url: URL of the license, used for links.
|
|
title: Title for the license, like 'Creative Commons Attribution 3.0'.
|
|
image: A button shown on each page for the license.
|
|
|
|
mail
|
|
----
|
|
|
|
This is for configuring out-going email. We use PEAR's Mail module,
|
|
see: http://pear.php.net/manual/en/package.mail.mail.factory.php
|
|
|
|
backend: the backend to use for mail, one of 'mail', 'sendmail', and
|
|
'smtp'. Defaults to PEAR's default, 'mail'.
|
|
params: if the mail backend requires any parameters, you can provide
|
|
them in an associative array.
|
|
|
|
nickname
|
|
--------
|
|
|
|
This is for configuring nicknames in the service.
|
|
|
|
blacklist: an array of strings for usernames that may not be
|
|
registered. A default array exists for strings that are
|
|
used by StatusNet (e.g. 'doc', 'main', 'avatar', 'theme')
|
|
but you may want to add others if you have other software
|
|
installed in a subdirectory of StatusNet or if you just
|
|
don't want certain words used as usernames.
|
|
featured: an array of nicknames of 'featured' users of the site.
|
|
Can be useful to draw attention to well-known users, or
|
|
interesting people, or whatever.
|
|
|
|
avatar
|
|
------
|
|
|
|
For configuring avatar access.
|
|
|
|
dir: Directory to look for avatar files and to put them into.
|
|
Defaults to avatar subdirectory of install directory; if
|
|
you change it, make sure to change path, too.
|
|
path: Path to avatars. Defaults to path for avatar subdirectory,
|
|
but you can change it if you wish. Note that this will
|
|
be included with the avatar server, too.
|
|
server: If set, defines another server where avatars are stored in the
|
|
root directory. Note that the 'avatar' subdir still has to be
|
|
writeable. You'd typically use this to split HTTP requests on
|
|
the client to speed up page loading, either with another
|
|
virtual server or with an NFS or SAMBA share. Clients
|
|
typically only make 2 connections to a single server at a
|
|
time <http://ur1.ca/6ih>, so this can parallelize the job.
|
|
Defaults to null.
|
|
|
|
public
|
|
------
|
|
|
|
For configuring the public stream.
|
|
|
|
localonly: If set to true, only messages posted by users of this
|
|
service (rather than other services, filtered through OMB)
|
|
are shown in the public stream. Default true.
|
|
blacklist: An array of IDs of users to hide from the public stream.
|
|
Useful if you have someone making excessive Twitterfeed posts
|
|
to the site, other kinds of automated posts, testing bots, etc.
|
|
autosource: Sources of notices that are from automatic posters, and thus
|
|
should be kept off the public timeline. Default empty.
|
|
|
|
theme
|
|
-----
|
|
|
|
server: Like avatars, you can speed up page loading by pointing the
|
|
theme file lookup to another server (virtual or real).
|
|
Defaults to NULL, meaning to use the site server.
|
|
dir: Directory where theme files are stored. Used to determine
|
|
whether to show parts of a theme file. Defaults to the theme
|
|
subdirectory of the install directory.
|
|
path: Path part of theme URLs, before the theme name. Relative to the
|
|
theme server. It may make sense to change this path when upgrading,
|
|
(using version numbers as the path) to make sure that all files are
|
|
reloaded by caching clients or proxies. Defaults to null,
|
|
which means to use the site path + '/theme'.
|
|
|
|
xmpp
|
|
----
|
|
|
|
For configuring the XMPP sub-system.
|
|
|
|
enabled: Whether to accept and send messages by XMPP. Default false.
|
|
server: server part of XMPP ID for update user.
|
|
port: connection port for clients. Default 5222, which you probably
|
|
shouldn't need to change.
|
|
user: username for the client connection. Users will receive messages
|
|
from 'user'@'server'.
|
|
resource: a unique identifier for the connection to the server. This
|
|
is actually used as a prefix for each XMPP component in the system.
|
|
password: password for the user account.
|
|
host: some XMPP domains are served by machines with a different
|
|
hostname. (For example, @gmail.com GTalk users connect to
|
|
talk.google.com). Set this to the correct hostname if that's the
|
|
case with your server.
|
|
encryption: Whether to encrypt the connection between StatusNet and the
|
|
XMPP server. Defaults to true, but you can get
|
|
considerably better performance turning it off if you're
|
|
connecting to a server on the same machine or on a
|
|
protected network.
|
|
debug: if turned on, this will make the XMPP library blurt out all of
|
|
the incoming and outgoing messages as XML stanzas. Use as a
|
|
last resort, and never turn it on if you don't have queues
|
|
enabled, since it will spit out sensitive data to the browser.
|
|
public: an array of JIDs to send _all_ notices to. This is useful for
|
|
participating in third-party search and archiving services.
|
|
|
|
invite
|
|
------
|
|
|
|
For configuring invites.
|
|
|
|
enabled: Whether to allow users to send invites. Default true.
|
|
|
|
openid
|
|
------
|
|
|
|
For configuring OpenID.
|
|
|
|
enabled: Whether to allow users to register and login using OpenID. Default
|
|
true.
|
|
|
|
tag
|
|
---
|
|
|
|
Miscellaneous tagging stuff.
|
|
|
|
dropoff: Decay factor for tag listing, in seconds.
|
|
Defaults to exponential decay over ten days; you can twiddle
|
|
with it to try and get better results for your site.
|
|
|
|
popular
|
|
-------
|
|
|
|
Settings for the "popular" section of the site.
|
|
|
|
dropoff: Decay factor for popularity listing, in seconds.
|
|
Defaults to exponential decay over ten days; you can twiddle
|
|
with it to try and get better results for your site.
|
|
|
|
daemon
|
|
------
|
|
|
|
For daemon processes.
|
|
|
|
piddir: directory that daemon processes should write their PID file
|
|
(process ID) to. Defaults to /var/run/, which is where this
|
|
stuff should usually go on Unix-ish systems.
|
|
user: If set, the daemons will try to change their effective user ID
|
|
to this user before running. Probably a good idea, especially if
|
|
you start the daemons as root. Note: user name, like 'daemon',
|
|
not 1001.
|
|
group: If set, the daemons will try to change their effective group ID
|
|
to this named group. Again, a name, not a numerical ID.
|
|
|
|
memcached
|
|
---------
|
|
|
|
You can get a significant boost in performance by caching some
|
|
database data in memcached <http://www.danga.com/memcached/>.
|
|
|
|
enabled: Set to true to enable. Default false.
|
|
server: a string with the hostname of the memcached server. Can also
|
|
be an array of hostnames, if you've got more than one server.
|
|
base: memcached uses key-value pairs to store data. We build long,
|
|
funny-looking keys to make sure we don't have any conflicts. The
|
|
base of the key is usually a simplified version of the site name
|
|
(like "Identi.ca" => "identica"), but you can overwrite this if
|
|
you need to. You can safely ignore it if you only have one
|
|
StatusNet site using your memcached server.
|
|
port: Port to connect to; defaults to 11211.
|
|
|
|
sphinx
|
|
------
|
|
|
|
You can get a significant boost in performance using Sphinx Search
|
|
instead of your database server to search for users and notices.
|
|
<http://sphinxsearch.com/>.
|
|
|
|
enabled: Set to true to enable. Default false.
|
|
server: a string with the hostname of the sphinx server.
|
|
port: an integer with the port number of the sphinx server.
|
|
|
|
emailpost
|
|
---------
|
|
|
|
For post-by-email.
|
|
|
|
enabled: Whether to enable post-by-email. Defaults to true. You will
|
|
also need to set up maildaemon.php.
|
|
|
|
sms
|
|
---
|
|
|
|
For SMS integration.
|
|
|
|
enabled: Whether to enable SMS integration. Defaults to true. Queues
|
|
should also be enabled.
|
|
|
|
twitter
|
|
-------
|
|
|
|
For Twitter integration
|
|
|
|
enabled: Whether to enable Twitter integration. Defaults to true.
|
|
Queues should also be enabled.
|
|
|
|
integration
|
|
-----------
|
|
|
|
A catch-all for integration with other systems.
|
|
|
|
source: The name to use for the source of posts to Twitter. Defaults
|
|
to 'statusnet', but if you request your own source name from
|
|
Twitter <http://twitter.com/help/request_source>, you can use
|
|
that here instead. Status updates on Twitter will then have
|
|
links to your site.
|
|
taguri: base for tag:// URIs. Defaults to site-server + ',2009'.
|
|
|
|
inboxes
|
|
-------
|
|
|
|
For notice inboxes.
|
|
|
|
enabled: A three-valued flag for whether to use notice inboxes (see
|
|
upgrading info above for notes about this change). Can be
|
|
'false', 'true', or '"transitional"'.
|
|
|
|
throttle
|
|
--------
|
|
|
|
For notice-posting throttles.
|
|
|
|
enabled: Whether to throttle posting. Defaults to false.
|
|
count: Each user can make this many posts in 'timespan' seconds. So, if count
|
|
is 100 and timespan is 3600, then there can be only 100 posts
|
|
from a user every hour.
|
|
timespan: see 'count'.
|
|
|
|
profile
|
|
-------
|
|
|
|
Profile management.
|
|
|
|
banned: an array of usernames and/or profile IDs of 'banned' profiles.
|
|
The site will reject any notices by these users -- they will
|
|
not be accepted at all. (Compare with blacklisted users above,
|
|
whose posts just won't show up in the public stream.)
|
|
|
|
newuser
|
|
-------
|
|
|
|
Options with new users.
|
|
|
|
default: nickname of a user account to automatically subscribe new
|
|
users to. Typically this would be system account for e.g.
|
|
service updates or announcements. Users are able to unsub
|
|
if they want. Default is null; no auto subscribe.
|
|
welcome: nickname of a user account that sends welcome messages to new
|
|
users. Can be the same as 'default' account, although on
|
|
busy servers it may be a good idea to keep that one just for
|
|
'urgent' messages. Default is null; no message.
|
|
|
|
If either of these special user accounts are specified, the users should
|
|
be created before the configuration is updated.
|
|
|
|
snapshot
|
|
--------
|
|
|
|
The software will, by default, send statistical snapshots about the
|
|
local installation to a stats server on the status.net Web site. This
|
|
data is used by the developers to prioritize development decisions. No
|
|
identifying data about users or organizations is collected. The data
|
|
is available to the public for review. Participating in this survey
|
|
helps StatusNet developers take your needs into account when updating
|
|
the software.
|
|
|
|
run: string indicating when to run the statistics. Values can be 'web'
|
|
(run occasionally at Web time), 'cron' (run from a cron script),
|
|
or 'never' (don't ever run). If you set it to 'cron', remember to
|
|
schedule the script to run on a regular basis.
|
|
frequency: if run value is 'web', how often to report statistics.
|
|
Measured in Web hits; depends on how active your site is.
|
|
Default is 10000 -- that is, one report every 10000 Web hits,
|
|
on average.
|
|
reporturl: URL to post statistics to. Defaults to StatusNet developers'
|
|
report system, but if they go evil or disappear you may
|
|
need to update this to another value. Note: if you
|
|
don't want to report stats, it's much better to
|
|
set 'run' to 'never' than to set this value to something
|
|
nonsensical.
|
|
|
|
attachments
|
|
-----------
|
|
|
|
The software lets users upload files with their notices. You can configure
|
|
the types of accepted files by mime types and a trio of quota options:
|
|
per file, per user (total), per user per month.
|
|
|
|
We suggest the use of the pecl file_info extension to handle mime type
|
|
detection.
|
|
|
|
supported: an array of mime types you accept to store and distribute,
|
|
like 'image/gif', 'video/mpeg', 'audio/mpeg', etc. Make sure you
|
|
setup your server to properly recognize the types you want to
|
|
support.
|
|
uploads: false to disable uploading files with notices (true by default).
|
|
filecommand: The required MIME_Type library may need to use the 'file'
|
|
command. It tries the one in the Web server's path, but if
|
|
you're having problems with uploads, try setting this to the
|
|
correct value. Note: 'file' must accept '-b' and '-i' options.
|
|
|
|
For quotas, be sure you've set the upload_max_filesize and post_max_size
|
|
in php.ini to be large enough to handle your upload. In httpd.conf
|
|
(if you're using apache), check that the LimitRequestBody directive isn't
|
|
set too low (it's optional, so it may not be there at all).
|
|
|
|
file_quota: maximum size for a single file upload in bytes. A user can send
|
|
any amount of notices with attachments as long as each attachment
|
|
is smaller than file_quota.
|
|
user_quota: total size in bytes a user can store on this server. Each user
|
|
can store any number of files as long as their total size does
|
|
not exceed the user_quota.
|
|
monthly_quota: total size permitted in the current month. This is the total
|
|
size in bytes that a user can upload each month.
|
|
dir: directory accessible to the Web process where uploads should go.
|
|
Defaults to the 'file' subdirectory of the install directory, which
|
|
should be writeable by the Web user.
|
|
server: server name to use when creating URLs for uploaded files.
|
|
Defaults to null, meaning to use the default Web server. Using
|
|
a virtual server here can speed up Web performance.
|
|
path: URL path, relative to the server, to find files. Defaults to
|
|
main path + '/file/'.
|
|
filecommand: command to use for determining the type of a file. May be
|
|
skipped if fileinfo extension is installed. Defaults to
|
|
'/usr/bin/file'.
|
|
|
|
group
|
|
-----
|
|
|
|
Options for group functionality.
|
|
|
|
maxaliases: maximum number of aliases a group can have. Default 3. Set
|
|
to 0 or less to prevent aliases in a group.
|
|
|
|
oohembed
|
|
--------
|
|
|
|
oEmbed endpoint for multimedia attachments (links in posts).
|
|
|
|
endpoint: oohembed endpoint using http://oohembed.com/ software.
|
|
|
|
search
|
|
------
|
|
|
|
Some stuff for search.
|
|
|
|
type: type of search. Ignored if PostgreSQL or Sphinx are enabled. Can either
|
|
be 'fulltext' (default) or 'like'. The former is faster and more efficient
|
|
but requires the lame old MyISAM engine for MySQL. The latter
|
|
will work with InnoDB but could be miserably slow on large
|
|
systems. We'll probably add another type sometime in the future,
|
|
with our own indexing system (maybe like MediaWiki's).
|
|
|
|
sessions
|
|
--------
|
|
|
|
Session handling.
|
|
|
|
handle: boolean. Whether we should register our own PHP session-handling
|
|
code (using the database and memcache if enabled). Defaults to false.
|
|
Setting this to true makes some sense on large or multi-server
|
|
sites, but it probably won't hurt for smaller ones, either.
|
|
debug: whether to output debugging info for session storage. Can help
|
|
with weird session bugs, sometimes. Default false.
|
|
|
|
background
|
|
----------
|
|
|
|
Users can upload backgrounds for their pages; this section defines
|
|
their use.
|
|
|
|
server: the server to use for background. Using a separate (even
|
|
virtual) server for this can speed up load times. Default is
|
|
null; same as site server.
|
|
dir: directory to write backgrounds too. Default is '/background/'
|
|
subdir of install dir.
|
|
path: path to backgrounds. Default is sub-path of install path; note
|
|
that you may need to change this if you change site-path too.
|
|
|
|
twitterbridge
|
|
-------------
|
|
|
|
A bi-direction bridge to Twitter (http://twitter.com/).
|
|
|
|
enabled: default false. If true, will show user's Twitter friends'
|
|
notices in their inbox and faves pages, only to the user. You
|
|
must also run the twitterstatusfetcher.php script.
|
|
|
|
ping
|
|
----
|
|
|
|
Using the "XML-RPC Ping" method initiated by weblogs.com, the site can
|
|
notify third-party servers of updates.
|
|
|
|
notify: an array of URLs for ping endpoints. Default is the empty
|
|
array (no notification).
|
|
|
|
design
|
|
------
|
|
|
|
Default design (colors and background) for the site. Actual appearance
|
|
depends on the theme. Null values mean to use the theme defaults.
|
|
|
|
backgroundcolor: Hex color of the site background.
|
|
contentcolor: Hex color of the content area background.
|
|
sidebarcolor: Hex color of the sidebar background.
|
|
textcolor: Hex color of all non-link text.
|
|
linkcolor: Hex color of all links.
|
|
backgroundimage: Image to use for the background.
|
|
disposition: Flags for whether or not to tile the background image.
|
|
|
|
Plugins
|
|
=======
|
|
|
|
Beginning with the 0.7.x branch, StatusNet has supported a simple but
|
|
powerful plugin architecture. Important events in the code are named,
|
|
like 'StartNoticeSave', and other software can register interest
|
|
in those events. When the events happen, the other software is called
|
|
and has a choice of accepting or rejecting the events.
|
|
|
|
In the simplest case, you can add a function to config.php and use the
|
|
Event::addHandler() function to hook an event:
|
|
|
|
function AddGoogleLink($action)
|
|
{
|
|
$action->menuItem('http://www.google.com/', _('Google'), _('Search engine'));
|
|
return true;
|
|
}
|
|
|
|
Event::addHandler('EndPrimaryNav', 'AddGoogleLink');
|
|
|
|
This adds a menu item to the end of the main navigation menu. You can
|
|
see the list of existing events, and parameters that handlers must
|
|
implement, in EVENTS.txt.
|
|
|
|
The Plugin class in lib/plugin.php makes it easier to write more
|
|
complex plugins. Sub-classes can just create methods named
|
|
'onEventName', where 'EventName' is the name of the event (case
|
|
matters!). These methods will be automatically registered as event
|
|
handlers by the Plugin constructor (which you must call from your own
|
|
class's constructor).
|
|
|
|
Several example plugins are included in the plugins/ directory. You
|
|
can enable a plugin with the following line in config.php:
|
|
|
|
addPlugin('Example', array('param1' => 'value1',
|
|
'param2' => 'value2'));
|
|
|
|
This will look for and load files named 'ExamplePlugin.php' or
|
|
'Example/ExamplePlugin.php' either in the plugins/ directory (for
|
|
plugins that ship with StatusNet) or in the local/ directory (for
|
|
plugins you write yourself or that you get from somewhere else) or
|
|
local/plugins/.
|
|
|
|
Plugins are documented in their own directories.
|
|
|
|
Troubleshooting
|
|
===============
|
|
|
|
The primary output for StatusNet is syslog, unless you configured a
|
|
separate logfile. This is probably the first place to look if you're
|
|
getting weird behaviour from StatusNet.
|
|
|
|
If you're tracking the unstable version of StatusNet in the git
|
|
repository (see below), and you get a compilation error ("unexpected
|
|
T_STRING") in the browser, check to see that you don't have any
|
|
conflicts in your code.
|
|
|
|
If you upgraded to StatusNet 0.8.2 without reading the "Notice
|
|
inboxes" section above, and all your users' 'Personal' tabs are empty,
|
|
read the "Notice inboxes" section above.
|
|
|
|
Myths
|
|
=====
|
|
|
|
These are some myths you may see on the Web about StatusNet.
|
|
Documentation from the core team about StatusNet has been pretty
|
|
sparse, so some backtracking and guesswork resulted in some incorrect
|
|
assumptions.
|
|
|
|
- "Set $config['db']['debug'] = 5 to debug the database." This is an
|
|
extremely bad idea. It's a tool built into DB_DataObject that will
|
|
emit oodles of print lines directly to the browser of your users.
|
|
Among these lines will be your database username and password. Do
|
|
not enable this option on a production Web site for any reason.
|
|
|
|
- "Edit dataobject.ini with the following settings..." dataobject.ini
|
|
is a development file for the DB_DataObject framework and is not
|
|
used by the running software. It was removed from the StatusNet
|
|
distribution because its presence was confusing. Do not bother
|
|
configuring dataobject.ini, and do not put your database username
|
|
and password into the file on a production Web server; unscrupulous
|
|
persons may try to read it to get your passwords.
|
|
|
|
Unstable version
|
|
================
|
|
|
|
If you're adventurous or impatient, you may want to install the
|
|
development version of StatusNet. To get it, use the git version
|
|
control tool <http://git-scm.com/> like so:
|
|
|
|
git clone git@gitorious.org:statusnet/mainline.git
|
|
|
|
This is the version of the software that runs on Identi.ca and the
|
|
status.net hosted service. Using it is a mixed bag. On the positive
|
|
side, it usually includes the latest security and bug fix patches. On
|
|
the downside, it may also include changes that require admin
|
|
intervention (like running a script or even raw SQL!) that may not be
|
|
documented yet. It may be a good idea to test this version before
|
|
installing it on your production machines.
|
|
|
|
To keep it up-to-date, use 'git pull'. Watch for conflicts!
|
|
|
|
Further information
|
|
===================
|
|
|
|
There are several ways to get more information about StatusNet.
|
|
|
|
* There is a mailing list for StatusNet developers and admins at
|
|
http://mail.status.net/mailman/listinfo/statusnet-dev
|
|
* The #statusnet IRC channel on freenode.net <http://www.freenode.net/>.
|
|
* The StatusNet wiki, http://status.net/wiki/
|
|
* The StatusNet blog, http://status.net/blog/
|
|
* The StatusNet status update, <http://status.status.net/status> (!)
|
|
|
|
Feedback
|
|
========
|
|
|
|
* Microblogging messages to http://identi.ca/evan are very welcome.
|
|
* StatusNet's Trac server has a bug tracker for any defects you may find,
|
|
or ideas for making things better. http://status.net/trac/
|
|
* e-mail to evan@status.net will usually be read and responded to very
|
|
quickly, unless the question is really hard.
|
|
|
|
Credits
|
|
=======
|
|
|
|
The following is an incomplete list of developers who've worked on
|
|
StatusNet. Apologies for any oversight; please let evan@status.net know
|
|
if anyone's been overlooked in error.
|
|
|
|
* Evan Prodromou, founder and lead developer, StatusNet, Inc.
|
|
* Zach Copley, StatusNet, Inc.
|
|
* Earle Martin, StatusNet, Inc.
|
|
* Marie-Claude Doyon, designer, StatusNet, Inc.
|
|
* Sarven Capadisli, StatusNet, Inc.
|
|
* Robin Millette, StatusNet, Inc.
|
|
* Ciaran Gultnieks
|
|
* Michael Landers
|
|
* Ori Avtalion
|
|
* Garret Buell
|
|
* Mike Cochrane
|
|
* Matthew Gregg
|
|
* Florian Biree
|
|
* Erik Stambaugh
|
|
* 'drry'
|
|
* Gina Haeussge
|
|
* Tryggvi Björgvinsson
|
|
* Adrian Lang
|
|
* Ori Avtalion
|
|
* Meitar Moscovitz
|
|
* Ken Sheppardson (Trac server, man-about-town)
|
|
* Tiago 'gouki' Faria (i18n manager)
|
|
* Sean Murphy
|
|
* Leslie Michael Orchard
|
|
* Eric Helgeson
|
|
* Ken Sedgwick
|
|
* Brian Hendrickson
|
|
* Tobias Diekershoff
|
|
* Dan Moore
|
|
* Fil
|
|
* Jeff Mitchell
|
|
* Brenda Wallace
|
|
* Jeffery To
|
|
* Federico Marani
|
|
* Craig Andrews
|
|
* mEDI
|
|
|
|
Thanks also to the developers of our upstream library code and to the
|
|
thousands of people who have tried out Identi.ca, installed StatusNet,
|
|
told their friends, and built the Open Microblogging network to what
|
|
it is today.
|