README
------
-Laconica 0.7.3 ("You Are The Everything")
-7 April 2009
+Laconica 0.7.4 ("Can't Get There From Here")
+29 May 2009
This is the README file for Laconica, the Open Source microblogging
platform. It includes installation instructions, descriptions of
New this version
================
-This is a minor bug-fix and feature release since version 0.7.2.1,
-released Mar 11 2009. Notable changes this version:
-
-- A plugin to allow a templating language for customization
-- A plugin for Piwik Analytics engine
-- A bookmarklet for posting a notice about a Web page you're reading
-- A welcome notice ('welcomebot') and default subscription for new users
-- Support for SSL for some or all pages on the site
-- Better handling of empty notice lists on many pages
-- Major improvements to the Twitter friend-sync offline processing
-- subscribers, subscriptions, groups are listed on the Personal page.
-- "Invite" link restored to main menu
-- Better memory handling in FOAF output
-- Fix for SUP support (FriendFeed)
-- Correct and intelligent redirect HTTP status codes
-- Fix DB collations for search and sort
-- Better H1s and Titles using user full names
-- Fixes to make the linkback plugin operational
-- Better indication that a notice is being published by Ajax (spinner)
-- Better and unified Atom output
-- Hiding "register" and "join now" messages when site is closed
-- ping, twitter and facebook queuehandlers working better
-- Updated RPM spec
+This is a minor bug-fix and feature release since version 0.7.3,
+released Apr 4 2009. Notable changes this version:
+
+- Improved handling of UTF-8 characters. The new code is *not* backwards
+ compatible by default; see "Upgrading" below for instructions on
+ converting existing databases to the correct character set.
+- Unroll joins for large queries. This greatly enhanced database
+ performance -- up to 50x for some queries -- at the expense of making
+ an extra DB hit for some queries.
+- Added an optional plugin to use WikiHashtags
+ (http://hashtags.wikia.com/) for the sidebar on hashtag pages.
+- Optimized Twitter friend synchronization.
+- Better error handling for Ajax posting of notices, including
+ HTTP errors and timeouts.
+- Experimental Comet plugin -- supports the cometd and the Bayeux
+ protocol. Using this plugin, you can show "real time" updates on the
+ public and tag pages. However, server configuration is complex.
+- If queues are enabled, update inboxes and memcached off-line. Speeds
+ up posting considerably.
+- Correctly shorten links posted through XMPP.
+- <link> elements for pagination, supported by some browsers like Opera.
+- Corrected date format in search API.
+- Made the public XRDS file work correctly.
Prerequisites
=============
- Facebook library. Used for the Facebook application.
- PEAR Services_oEmbed. Used for some multimedia integration.
- PEAR HTTP_Request is an oEmbed dependency.
-- PEAR Validat is an oEmbed dependency.e
-- PEAR Net_URL is an oEmbed dependency.2
+- PEAR Validate is an oEmbed dependency.
+- PEAR Net_URL2 is an oEmbed dependency.
+- Console_GetOpt for parsing command-line options.
A design goal of Laconica is that the basic Web functionality should
work on even the most restrictive commercial hosting services.
1. Unpack the tarball you downloaded on your Web server. Usually a
command like this will work:
- tar zxf laconica-0.7.3.tar.gz
+ tar zxf laconica-0.7.4.tar.gz
- ...which will make a laconica-0.7.3 subdirectory in your current
+ ...which will make a laconica-0.7.4 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 laconica-0.7.3 /var/www/mublog
+ mv laconica-0.7.4 /var/www/mublog
This will make your Laconica instance available in the mublog path of
your server, like "http://example.net/mublog". "microblog" or
Upgrading
=========
+IMPORTANT NOTE: Laconica 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 Laconica 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 Laconica 0.7.3. Try these step-by-step instructions; read
+procedure in Laconica 0.7.4. Try these step-by-step instructions; read
to the end first before trying them.
0. Download Laconica and set up all the prerequisites as if you were
3. When fixup_inboxes is finished, you can set the enabled flag to
'true'.
+UTF-8 Database
+--------------
+
+Laconica 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
=====================
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
------
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
-----
server: Like avatars, you can speed up page loading by pointing the
- theme file lookup to another server (virtual or real). The
- theme server's root path should map to the Laconica "theme"
- subdirectory. Defaults to NULL.
+ 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
----
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
+ Laconica site using your memcached server.
+port: Port to connect to; defaults to 11211.
sphinx
------
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 laconi.ca 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 Laconica 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 Laconica 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 reckognize 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.
+
+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.
+
Troubleshooting
===============
T_STRING") in the browser, check to see that you don't have any
conflicts in your code.
-If you upgraded to Laconica 0.7.3 without reading the "Notice inboxes"
+If you upgraded to Laconica 0.7.4 without reading the "Notice inboxes"
section above, and all your users' 'Personal' tabs are empty, read the
"Notice inboxes" section above.
* Ken Sedgwick
* Brian Hendrickson
* Tobias Diekershoff
+* Dan Moore
+* Fil
Thanks also to the developers of our upstream library code and to the
thousands of people who have tried out Identi.ca, installed Laconi.ca,
projects / quix0rs-gnu-social.git / blobdiff