diff options
Diffstat (limited to '_darcs/pristine/README')
| -rw-r--r-- | _darcs/pristine/README | 1162 |
1 files changed, 0 insertions, 1162 deletions
diff --git a/_darcs/pristine/README b/_darcs/pristine/README deleted file mode 100644 index a3ea5fa58..000000000 --- a/_darcs/pristine/README +++ /dev/null @@ -1,1162 +0,0 @@ ------- -README ------- - -Laconica 0.6.4 ("Catapult") -11 December 2008 - -This is the README file for 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 Laconica can be found in the -"doc" subdirectory or in the "help" section on-line. - -About -===== - -Laconica (pronounced "luh-KAWN-ih-kuh") 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, Pownce 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. - -Laconica 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. - -Laconica 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.0: - - http://www.openknowledge.org/ossd - -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 Laconica 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 LACONICA*. - -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 security improvement version from version -0.6.3 (release 24 Nov 2008). Notable features of version 0.6.4 include: - -- "private" installs won't show any data to the outside world; redirect - non-logged-in users to login. (See "Private" below) -- Ability to "block" a subscriber, which forces them to unsubscribe, - doesn't allow them to subscribe again, and doesn't allow them to send - @-replies -- Fine-grained control of subscriptions; users can choose not to receive - notices from other users over SMS, or IM, or both -- support for Mozilla microsummaries - (https://wiki.mozilla.org/Microsummaries) -- more efficient support for blacklisting users from the public page -- instructions on the public page for people who aren't logged in -- better registration instructions -- a check for license compatibility in receiving OMB notices -- HTML output in RSS 1.0, 2.0, and Atom feeds -- tuned and more reliable 'rememberme' cookies for username/password - and OpenID logins -- a utility for setting user passwords -- a "ban" configuration variable to ban certain users from posting - notices -- an configurable posting throttle to keep any one user from flooding - the site with messages. -- fine-tuned url-shortening: only shorten if it's needed, only expand - certain URLs, and handle failure of URL-shortening services reliably -- disable Ajax input for notices, subscribe, nudge, while the - request is processing -- early implementation of support for Last-Modified and ETag-based - caching -- initial microformats support -- redirect on bad nicknames in URLs -- correctly send emails in recipient's, not sender's, language -- correct email content type -- Change "Most Favorited" page to "Popular" -- properly support the "since" parameter in API calls -- Fix for changes in validate_credentials API call for the Twitter - bridge -- Fix for fatal error when sending email confirmation on registration -- Better replies for commands sent through the Ajax channel -- Add a User-Agent string for OMB requests -- Upgrade upstream library XMPPHP -- Upgrade upstream library JQuery Forms -- Code cleanup: checkboxes have proper <label> elements -- Code cleanup: consolidated various notice-listing code in one place -- Better support for unsubscribing from a remote user -- Stump of experimental Facebook application (not ready for use! code - review only!) -- Stump of experimental user account deletion (not ready for use! code - review only!) - -Prerequisites -============= - -The following software packages are *required* for this software to -run correctly. - -- PHP 5.2.x. 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 Laconica 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. - -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 Laconica site unable to send or receive XMPP - messages. - -A design goal of Laconica 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 Laconica 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 laconica-0.6.4.tar.gz - - ...which will make a laconica-0.6.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.6.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 - "laconica" 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. You should also take this moment to make your avatar subdirectory - writeable by the Web server. An insecure way to do this is: - - chmod a+w /var/www/mublog/avatar - - On some systems, this will probably work: - - chgrp www-data /var/www/mublog/avatar - chmod g+w /var/www/mublog/avatar - - 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 "avatar" and add the Web server's user to the group. - -4. Create a database to hold your microblog data. Something like this - should work: - - mysqladmin -u "username" --password="password" create laconica - - Note that Laconica 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.) - -5. Run the laconica.sql SQL script in the db subdirectory to create - the database tables in the database. A typical system would work - like this: - - mysql -u "username" --password="password" laconica < /var/www/mublog/db/laconica.sql - - You may want to test by logging into the database and checking that - the tables were created. Here's an example: - - SHOW TABLES; - -6. Create a new database account that Laconica will use to access the - database. If you have shell access, this will probably work from the - MySQL shell: - - GRANT SELECT,INSERT,DELETE,UPDATE on laconica.* - 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 as this new - user and testing that you can SELECT from some of the tables in the - DB (use SHOW TABLES to see which ones are there). - -7. Copy the config.php.sample in the Laconica directory to config.php. - -8. Edit config.php to set the basic configuration for your system. - (See descriptions below for basic config options.) Note that there - are lots of options and if you try to do them all at once, you will - have a hard time making sure what's working and what's not. So, - stick with the basics at first. In particular, customizing the - 'site' and 'db' settings will almost definitely be needed. - -9. At this point, you should be able to navigate in a browser 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, Laconica will have big long sloppy URLs that are hard for -people to remember or use. For example, a user's home profile might be -found at: - - http://example.org/mublog/index.php?action=showstream&nickname=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.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 Laconica - 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 Laconica installation on your server. Typically this will - be the path to your Laconica 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. - -If you have problems with the .htaccess file on versions of Apache -earlier than 2.2.x, try changing the regular expressions in the -htaccess.sample file that use "\w" to just use ".". - -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 ---- - -Laconica 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 message 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 Laconica database. This will - usually work: - - mysql -u "lacuser" --password="lacpassword" laconica < 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/laconica/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 Laconica, a working -config.php, and access to the Laconica 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. - - Laconica 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 Laconica; 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 Laconica 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 Laconica - 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 - Laconica dir, "." should suffice. - -This will run six (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. - -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. - -Twitter Friends Syncing ------------------------ - -As of Laconica 0.6.3, users may set a flag in their settings ("Subscribe -to my Twitter friends here" under the Twitter tab) to have Laconica -attempt to locate and subscribe to "friends" (people they "follow") on -Twitter who also have accounts on your Laconica system, and who have -previously set up a link for automatically posting notices to Twitter. - -Optionally, there is a script (./scripts/synctwitterfriends.php), meant -to be run periodically from a job scheduler (e.g.: cron under Unix), to -look for new additions to users' friends lists. Note that the friends -syncing only subscribes users to each other, it does not unsubscribe -users when they stop following each other on Twitter. - -Sample cron job: - -# Update Twitter friends subscriptions every half hour -0,30 * * * * /path/to/php /path/to/laconica/scripts/synctwitterfriends.php>&/dev/null - -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 -Laconica instance. - -1. Choose your sitemap URL layout. Laconica 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 Laconica 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 Laconica: "stoica", -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. - -Translation ------------ - -Translations in Laconica 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 Laconica are very easy: -you can use the Web interface at http://laconi.ca/entrans/ 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 Laconica. You can make -backups of a working Laconica 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 -========= - -If you've been using Laconica 0.6, 0.5 or lower, or if you've been -tracking the "darcs" version of the software, you will probably want -to upgrade and keep your existing data. There is no automated upgrade -procedure in Laconica 0.6.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 - 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 Laconica directory to a backup spot, like "mublog.bak". -7. Unpack your Laconica 0.6 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. Go to your Laconica directory and run the - rebuilddb.sh script like this: - - ./scripts/rebuilddb.sh rootuser rootpassword database db/laconica.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 Laconica runs as. -11. Use mysql 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, stoica.ini, has been renamed to -laconica.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'. - -Configuration options -===================== - -The sole configuration file for Laconica (excepting configurations for -dependency software) is config.php in your Laconica 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. - -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 Laconica to save logging - information to. You may want to use this if you don't have - access to syslog. -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. -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. - -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 Laconica 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 'laconica', you'll need - to set this to point to the location of the - laconica.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. - -syslog ------- - -By default, Laconica sites log error messages to the syslog facility. -(You can override this using the 'logfile' parameter described above). - -appname: The name that Laconica uses to log messages. By default it's - "laconica", 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. - -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. - -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 Laconica (e.g. 'doc', 'main', 'avatar', 'theme') - but you may want to add others if you have other software - installed in a subdirectory of Laconica 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. - -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. - -theme ------ - -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. - -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 Laconica 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. - -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. - -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. - -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. - -integration ------------ - -A catch-all for integration with other systems. - -source: The name to use for the source of posts to Twitter. Defaults - to 'laconica', 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. - -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.) - -Troubleshooting -=============== - -The primary output for Laconica is syslog, unless you configured a -separate logfile. This is probably the first place to look if you're -getting weird behaviour from Laconica. - -If you're tracking the unstable version of Laconica in the darcs -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 Laconica 0.6.4 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 Laconica. -Documentation from the core team about Laconica 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 Laconica - 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 Laconica. To get it, use the darcs version -control tool (http://darcs.net/) like so: - - darcs get http://laconi.ca/darcs/ mublog - -To keep it up-to-date, use 'darcs pull'. Watch for conflicts! - -Further information -=================== - -There are several ways to get more information about Laconica. - -* There is a mailing list for Laconica developers and admins at - http://mail.laconi.ca/mailman/listinfo/laconica-dev -* The #laconica IRC channel on freenode.net (http://www.freenode.net/). -* The Laconica wiki, http://laconi.ca/trac/ - -Feedback -======== - -* Microblogging messages to http://identi.ca/evan are very welcome. -* Laconica's Trac server has a bug tracker for any defects you may find, - or ideas for making things better. http://laconi.ca/trac/ -* e-mail to evan@identi.ca 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 -Laconi.ca. Apologies for any oversight; please let evan@identi.ca know -if anyone's been overlooked in error. - -* Evan Prodromou, founder and lead developer, Control Yourself, Inc. -* Zach Copley, Control Yourself, Inc. -* Earle Martin, Control Yourself, Inc. -* Marie-Claude Doyon, designer, Control Yourself, Inc. -* Sarven Capadisli, Control Yourself, Inc. -* Robin Millette, Control Yourself, Inc. -* Ciaran Gultnieks -* Michael Landers -* Ori Avtalion -* Garret Buell -* Mike Cochrane -* Matthew Gregg -* Florian Biree -* Erik Stambaugh -* 'drry' -* Gina Haeussge -* Ken Sheppardson (Trac server, man-about-town) -* Tiago 'gouki' Faria (entrans) -* Tryggvi Björgvinsson - -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, -told their friends, and built the Open Microblogging network to what -it is today. |