Install.txt

Installation and Upgrading Instructions StatusNet 0.9.5 ("What's The Frequency, Kenneth?") Release date: 10 September 2010

This document describes how to obtain and install the latest version of StatusNet, the Open Source microblogging platform. It includes installation instructions, pointers to sources for additional information, troubleshooting remedies and frequently asked questions regarding the installation process.

Information on using and configuring StatusNet can be found in the "doc" subdirectory (of the installation package) or on StatusNet's documentation wiki:

http://status.net/wiki/Main_Page

1. Introduction to StatusNet and Open Source Microblogging --

StatusNet is a Free and Open Source microblogging platform. It allows people in a community, company or group to exchange short (140 characters, by default, although this limit can be expanded to whatever suits your needs) messages (or "status updates") to stay connected. Users can choose which people to connect with and receive only their friends' or colleagues' updates. It provides a similar service to sites like Twitter, Google Buzz, or Yammer.

With some additional configuring, status messages can be sent to mobile phones, instant messenger programs (XMPP), and specially-designed desktop clients that support the Twitter API.

StatusNet supports an open standard called OStatus  that lets users in different networks follow each other. It enables a distributed social network spread all across the Web.

StatusNet was originally developed for the Open Software Service, 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.  also offers this software as a Web service, requiring no installation on your part. See  for details. 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.

A commercial software subscription is available from StatusNet Inc. It includes 24-hour technical support and developer support. More information at http://status.net/contact or email sales@status.net.

2. 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 .

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*.

Documentation in the /doc-src/ directory is available under the Creative Commons Attribution 3.0 Unported license, with attribution to "StatusNet". See http://creativecommons.org/licenses/by/3.0/ for details.

CSS and images in the /theme/ directory are available under the Creative Commons Attribution 3.0 Unported license, with attribution to "StatusNet". See http://creativecommons.org/licenses/by/3.0/ for details.

Our understanding and intention is that if you add your own theme that uses only CSS and images, those files are not subject to the copyleft requirements of the Affero General Public License 3.0. See http://wordpress.org/news/2009/07/themes-are-gpl-too/. This is not legal advice; consult your lawyer.

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.

3. New in StatusNet 0.9.5 -

This is a security, bug and feature release since version 0.9.4, which was released 16 August 2010.

For best compatibility with client software and site federation, and a lot of bug fixes, it is highly recommended that all public sites upgrade to the new version.

Notable changes this version:

- Change of license for default themes and documentation from AGPLv3 to CC-By 3.0 Unported. - An experimental TinyMCE plugin to do in-browser rich editing of status updates. Does not support StatusNet syntax like @-replies or #hashtags very well. - An experimental plugin to add titles to notices. - A plugin to support the Echo  commenting system. - A plugin to support the Disqus  commenting system. - Changes to OStatus support to make StatusNet work for the Social Web Acid Test Level 0 . - Themes now support a theme.ini file for theme configuration, including defining a "base" theme. - Improved two-way Twitter integration, including support for repeats and retweets, replies, and faves going both ways across the bridge, as well as better parsing of Twitter statuses.

A full changelog is available at:

http://status.net/wiki/StatusNet_0.9.5.

4. Obtaining the Software -

The latest version of StatusNet is always available from the following URL:

http://status.net/download

5. Before Installing StatusNet --

The following software packages are *required* for StatusNet 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. Ver. 5.2.6 or later is needed for XMPP background daemons on 64-bit platforms. PHP 5.3.x should work correctly in this release, but problems with some plugins are possible.


 * 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, naturally) 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.

Additionally, your PHP installation must include the following PHP extensions:


 * Curl (for fetching files by HTTP.)
 * XMLWriter (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.)

- 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.

6. Installing StatusNet ---

Installing the basic StatusNet Web component is a relatively straightforward process, especially if you have previously installed PHP/MySQL packages.

6.1. Unpack the tarball you downloaded on your Web server. Usually a command like this will work:

tar zxf statusnet-0.9.5.tar.gz

This will make a "statusnet-0.9.5" 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.)

6.2. Move the installation to a directory of your choosing in your Web root directory. Usually something like this will work:

mv statusnet-0.9.5 /var/www/statusnet

This will make your StatusNet instance available in the /statusnet path of your server, (such as "http://example.net/statusnet"); you can, however, give the directory any name you wish. If you know how to configure virtual hosts on your web server, you can also try setting up "http://micro.example.net/" or the like.

6.3. Make your target directory writeable by the Web server.

chmod a+w /var/www/statusnet/

On some systems, this will probably work:

chgrp www-data /var/www/statusnet/ chmod g+w /var/www/statusnet/

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 (name it something like "statusnet") and add the Web server's user to the group.

6.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/statusnet/avatar chmod a+w /var/www/statusnet/background chmod a+w /var/www/statusnet/file

You can also make the avatar, background, and file directories writeable by the Web server group, as noted above.

6.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.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 'statusnetuser'@'localhost' IDENTIFIED BY 'statusnetpassword';

You should change 'statusnetuser' and 'statusnetpassword' in the above examples to your preferred new username and password. You might want to test logging in to MySQL as this new user before continuing to the next step.

6.7. In a browser, navigate to the StatusNet install script; something like:

http://yourserver.example.com/statusnet/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.

6.8. You should now be able to navigate to your new StatusNet installation's main directory and view your Public Timeline, which will be empty until you register a new user and post your first notice. Before you do this, you should attempt to enable "fancy URLs" if your web server allows it.

6.9. Enabling 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/statusnet/index.php/statusnet/fred

On certain systems that don't support this kind of syntax, they'll look like this:

http://example.org/statusnet/index.php?p=statusnet/fred

It's also possible to configure the software so it looks like this instead:

http://example.org/statusnet/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.

6.9.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.

6.9.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 ("*/var/www/statusnet/").

6.9.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/statusnet/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 StatusNet 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

6.10. Installing StatusNet on Macintosh systems (pre-OS X 10.6)

Setting up StatusNet to work on Macintosh requires additional steps for machines running OS versions lower than 10.6 (Snow Leopard). Please consult the following wiki page for more information:

http://status.net/wiki/MacOSX

7. Upgrading From a Previous Version

If you're using an older version of StatusNet, at some point you will probably want to upgrade to the latest version to enjoy new features ad compatibility, while keeping your existing data in place.

While there is no automated upgrade procedure in StatusNet 0.9.5, you should be able to upgrade by carefully following these step-by-step instructions. Please read through them all the way to the end at least once before attempting to upgrade.

7.1. Download the latest version of StatusNet and set up all its prerequisites as if you were doing a new install.

7.2. Make backups of both your database and your Web directory. DO NOT ATTEMPT TO UPGRADE WITHOUT A BACKUP THAT YOU KNOW TO BE GOOD.

7.3. 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.

7.4. 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.

7.5. 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".

7.6. Once all writing processes to your site are turned off, make a final backup of the Web directory and database.

7.7. Move your existing StatusNet directory to a backup spot, like "statusnet.bak".

7.8. Unpack your StatusNet 0.9.5 tarball and move it to "statusnet" or wherever your previous installation existed.

7.9. Copy the config.php file and avatar directory from your old directory to your new directory.

7.10. Copy htaccess.sample to .htaccess in the new directory. Change the RewriteBase to use the correct path.

7.11. Rebuild the database. (You can safely skip this step and go to #12 if you're upgrading from another 0.9.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.8.0 or above, you can run a special upgrade script:

mysql -u -p db/08to09.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.

7.12. Use mysql or psql client to log into your database and make sure that the notice, user, profile, subscription etc. tables are non-empty.

7.13. Turn back on the Web server, and check that things still work.

7.14. 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.

7.15 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.

7.15.1. 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.

7.15.2. 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.

7.15.3. When you're ready, set $config['db']['utf8'] to true, so that new notices will be stored correctly.

8. Troubleshooting Installation Issues --

StatusNet provides a public forum -- http://forum.status.net/discussions -- for the discussion of issues related to the software, including problems encountered during installation. Please use the forum's search function for posts involving similar issues before starting a new thread.

A few common installation issues are discussed below, with suggested solutions.

Q. Where can I find debug information about my StatusNet install?

A. 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.

-

Q. I upgraded recently to StatusNet 0.9.5, and now all my users' 'Personal' tabs are empty.

A. Notice inboxes are now required. If you don't have inboxes enabled, StatusNet will no longer run. Set 'inboxes' to 'true' in config.php.

-

Q. I tried my domain name and also the ip-address of my site as Hostname while installing, but I cannot still install statusnet. It says: Can't connect to server 'mydomain' as 'myusername'.

A. It will be the host of the database server. Assuming that you are running the db on the same server as your StatusNet installation, try setting hostname to 'localhost'.

-

Q. When I try to install I get repeated variations of the following error message: "Warning: putenv [function.putenv]: Safe Mode warning".

A. You must disable php's safe mode before attempting to install, which may not be possible depending on your hosting environment. Check with your hosting service.

-

Q. How can I change the default language?

A. See the README file in the locales folder of your StatusNet directory (0.9.2 and above).

-

Q. I'm having a problem with DreamHost's one-click StatusNet install.

A.In March, DreamHost began offering StatusNet to its customers as part of the company's one-click install program. You'll find a discussion thread related to DreamHost install issues at:

http://forum.status.net/discussion/297/statusnet-on-dreamhost/#Item_44

-

Q. I've installed StatusNet successfully, and would like to post notices automatically to Twitter and Facebook from StatusNet.

A. You need to enable to TwitterBridge and Facebook plugins:

http://status.net/wiki/Documentation#twitter_bridge http://status.net/wiki/Facebook

9. Additional Resources ---

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 
 * The StatusNet wiki 
 * The StatusNet blog 
 * The StatusNet status update 

10. Feedback

http://status.net/bugs
 * Microblogging messages to http://support.status.net/ are very welcome.
 * The microblogging group http://identi.ca/group/statusnet is a good place to discuss the software.
 * StatusNet has a bug tracker for any defects you may find, or ideas for making things better:

11. Acknowledgments ---

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 Bjorgvinsson
 * 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
 * Brett Taylor
 * Brigitte Schuster

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.