8 This is the README file for Laconica, the Open Source microblogging
9 platform. It includes installation instructions, descriptions of
10 options you can set, warnings, tips, and general info for
11 administrators. Information on using Laconica can be found in the
12 "doc" subdirectory or in the "help" section on-line.
17 Laconica (pronounced "luh-KAWN-ih-kuh") is a Free and Open Source
18 microblogging platform. It helps people in a community, company or
19 group to exchange short (140 character) messages over the Web. Users
20 can choose which people to "follow" and receive only their friends' or
21 colleagues' status messages. It provides a similar service to sites
22 like Twitter, Jaiku, Pownce and Plurk.
24 With a little work, status messages can be sent to mobile phones,
25 instant messenger programs (GTalk/Jabber), and specially-designed
26 desktop clients that support the Twitter API.
28 Laconica supports an open standard called OpenMicroBlogging
29 (http://openmicroblogging.org/) that lets users on different Web sites
30 or in different companies subscribe to each others' notices. It
31 enables a distributed social network spread all across the Web.
33 Laconica was originally developed for the Open Software Service,
34 Identi.ca (http://identi.ca/). It is shared with you in hope that you
35 too make an Open Software Service available to your users. To learn
36 more, please see the Open Software Service Definition 1.0:
38 http://www.openknowledge.org/ossd
43 This program is free software: you can redistribute it and/or modify
44 it under the terms of the GNU Affero General Public License as
45 published by the Free Software Foundation, either version 3 of the
46 License, or (at your option) any later version.
48 This program is distributed in the hope that it will be useful, but
49 WITHOUT ANY WARRANTY; without even the implied warranty of
50 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
51 Affero General Public License for more details.
53 You should have received a copy of the GNU Affero General Public
54 License along with this program, in the file "COPYING". If not, see
55 <http://www.gnu.org/licenses/>.
57 IMPORTANT NOTE: The GNU Affero General Public License (AGPL) has
58 *different requirements* from the "regular" GPL. In particular, if
59 you make modifications to the Laconica source code on your server,
60 you *MUST MAKE AVAILABLE* the modified version of the source code
61 to your users under the same license. This is a legal requirement
62 of using the software, and if you do not wish to share your
63 modifications, *YOU MAY NOT INSTALL LACONICA*.
68 The following software packages are *required* for this software to
71 - PHP 5.2.x. It may be possible to run this software on earlier
72 versions of PHP, but many of the functions used are only available
74 - MySQL 5.x. The Laconica database is stored, by default, in a MySQL
75 server. It has been primarily tested on 5.x servers, although it may
76 be possible to install on earlier (or later!) versions. The server
77 *must* support the MyISAM storage engine -- the default for most
78 MySQL servers -- *and* the InnoDB storage engine.
79 - A Web server. Preferably, you should have Apache 2.2.x with the
80 mod_rewrite extension installed and enabled.
82 Your PHP installation must include the following PHP extensions:
84 - Curl. This is for fetching files by HTTP.
85 - XMLWriter. This is for formatting XML and HTML output.
86 - MySQL. For accessing the database.
88 For some functionality, you will also need the following extensions:
90 - Memcache. A client for the memcached server, which caches database
91 information in volatile memory. This is important for adequate
92 performance on high-traffic sites. You will also need a memcached
93 server to store the data in.
94 - Mailparse. Efficient parsing of email requires this extension.
95 Submission by email or SMS-over-email uses this extension.
97 You will almost definitely get 2-3 times better performance from your
98 site if you install a PHP bytecode cache/accelerator. Some well-known
99 examples are: eaccelerator, Turck mmcache, xcache, apc. Zend Optimizer
100 is a proprietary accelerator installed on some hosting sites.
105 A number of external PHP libraries are used to provide basic
106 functionality and optional functionality for your system. For your
107 convenience, they are available in the "extlib" directory of this
108 package, and you do not have to download and install them. However,
109 you may want to keep them up-to-date with the latest upstream version,
110 and the URLs are listed here for your convenience.
112 - DB_DataObject http://pear.php.net/package/DB_DataObject
113 - Validate http://pear.php.net/package/Validate
114 - OpenID from OpenIDEnabled (not the PEAR version!). We decided
115 to use the openidenabled.com version since it's more widely
116 implemented, and seems to be better supported.
117 http://openidenabled.com/php-openid/
118 - PEAR DB. Although this is an older data access system (new
119 packages should probably use PHP DBO), the OpenID libraries
120 depend on PEAR DB so we use it here, too. DB_DataObject can
121 also use PEAR MDB2, which may give you better performance
122 but won't work with OpenID.
123 http://pear.php.net/package/DB
124 - OAuth.php from http://oauth.googlecode.com/svn/code/php/
125 - markdown.php from http://michelf.com/projects/php-markdown/
126 - PEAR Mail, for sending out mail notifications
127 http://pear.php.net/package/Mail
128 - PEAR Net_SMTP, if you use the SMTP factory for notifications
129 http://pear.php.net/package/Net_SMTP
130 - XMPPHP, the follow-up to Class.Jabber.php. Probably the best XMPP
131 library available for PHP. http://xmpphp.googlecode.com/. Note that
132 as of this writing the version of this library that is available in
133 the extlib directory is *significantly different* from the upstream
134 version (patches have been submitted). Upgrading to the upstream
135 version may render your Laconica site unable to send or receive XMPP
138 A design goal of Laconica is that the basic Web functionality should
139 work on even the most restrictive commercial hosting services.
140 However, additional functionality, such as receiving messages by
141 Jabber/GTalk, require that you be able to run long-running processes
142 on your account. In addition, posting by email or from SMS require
143 that you be able to install a mail filter in your mail server.
148 Installing the basic Laconica Web component is relatively easy,
149 especially if you've previously installed PHP/MySQL packages.
151 1. Unpack the tarball you downloaded on your Web server. Usually a
152 command like this will work:
154 tar zxf laconica-0.6.0.tar.gz
156 ...which will make a laconica-0.6.0 subdirectory in your current
157 directory. (If you don't have shell access on your Web server, you
158 may have to unpack the tarball on your local computer and FTP the
159 files to the server.)
161 2. Move the tarball to a directory of your choosing in your Web root
162 directory. Usually something like this will work:
164 mv laconica-0.6.0 /var/www/mublog
166 This will make your Laconica instance available in the mublog path of
167 your server, like "http://example.net/mublog". "microblog" or
168 "laconica" might also be good path names. If you know how to
169 configure virtual hosts on your web server, you can try setting up
170 "http://micro.example.net/" or the like.
172 3. You should also take this moment to make your avatar subdirectory
173 writeable by the Web server. An insecure way to do this is:
175 chmod a+w /var/www/mublog/avatar
177 On some systems, this will probably work:
179 chgrp www-data /var/www/mublog/avatar
180 chmod g+w /var/www/mublog/avatar
182 If your Web server runs as another user besides "www-data", try
183 that user's default group instead. As a last resort, you can create
184 a new group like "avatar" and add the Web server's user to the group.
186 4. Create a database to hold your microblog data. Something like this
189 mysqladmin -u "username" --password="password" create laconica
191 Note that Laconica must have its own database; you can't share the
192 database with another program. You can name it whatever you want,
195 (If you don't have shell access to your server, you may need to use
196 a tool like PHPAdmin to create a database. Check your hosting
197 service's documentation for how to create a new MySQL database.)
199 5. Run the laconica.sql SQL script in the db subdirectory to create
200 the database tables in the database. A typical system would work
203 mysql -u "username" --password="password" laconica < /var/www/mublog/db/laconica.sql
205 You may want to test by logging into the database and checking that
206 the tables were created. Here's an example:
210 6. Create a new database account that Laconica will use to access the
211 database. If you have shell access, this will probably work from the
214 GRANT SELECT,INSERT,DELETE,UPDATE on laconica.*
215 TO 'lacuser'@'localhost'
216 IDENTIFIED BY 'lacpassword';
218 You should change 'lacuser' and 'lacpassword' to your preferred new
219 username and password. You may want to test logging in as this new
220 user and testing that you can SELECT from some of the tables in the
221 DB (use SHOW TABLES to see which ones are there).
223 7. Copy the config.php.sample in the Laconica directory to config.php.
225 8. Edit config.php to set the basic configuration for your system.
226 (See descriptions below for basic config options.) Note that there
227 are lots of options and if you try to do them all at once, you will
228 have a hard time making sure what's working and what's not. So,
229 stick with the basics at first.
231 9. At this point, you should be able to navigate in a browser to your
232 microblog's main directory and see the "Public Timeline", which
233 will be empty. If not, magic has happened! You can now register a
234 new user, post some notices, edit your profile, etc. However, you
235 may want to wait to do that stuff if you think you can set up
236 "fancy URLs" (see below), since some URLs are stored in the database.
241 By default, Laconica will have big long sloppy URLs that are hard for
242 people to remember or use. For example, a user's home profile might be
245 http://example.org/mublog/index.php?action=showstream&nickname=fred
247 It's possible to configure the software so it looks like this instead:
249 http://example.org/mublog/fred
251 These "fancy URLs" are more readable and memorable for users. To use
252 fancy URLs, you must either have Apache 2.2.x with .htaccess enabled
253 and mod_redirect enabled, -OR- know how to configure "url redirection"
256 1. Copy the htaccess.sample file to .htaccess in your Laconica
257 directory. Note: if you have control of your server's httpd.conf or
258 similar configuration files, it can greatly improve performance to
259 import the .htaccess file into your conf file instead. If you're
260 not sure how to do it, you may save yourself a lot of headache by
261 just leaving the .htaccess file.
263 2. Change the "RewriteBase" in the new .htaccess file to be the URL path
264 to your Laconica installation on your server. Typically this will
265 be the path to your Laconica directory relative to your Web root.
267 3. Add or uncomment or change a line in your config.php file so it says:
269 $config['site']['fancy'] = true;
271 You should now be able to navigate to a "fancy" URL on your server,
274 http://example.net/mublog/main/register
276 If you changed your HTTP server configuration, you may need to restart
279 If you have problems with the .htaccess file on versions of Apache
280 earlier than 2.2.x, try changing the regular expressions in the
281 htaccess.sample file that use "\w" to just use ".".
286 Laconica supports a cheap-and-dirty system for sending update messages
287 to mobile phones and for receiving updates from the mobile. Instead of
288 sending through the SMS network itself, which is costly and requires
289 buy-in from the wireless carriers, it simply piggybacks on the email
290 gateways that many carriers provide to their customers. So, SMS
291 configuration is essentially email configuration.
293 Each user sends to a made-up email address, which they keep a secret.
294 Incoming email that is "From" the user's SMS email address, and "To"
295 the users' secret email address on the site's domain, will be
296 converted to a message and stored in the DB.
298 For this to work, there *must* be a domain or sub-domain for which all
299 (or most) incoming email can pass through the incoming mail filter.
301 1. Run the SQL script carrier.sql in your Laconica database. This will
304 mysql -u "lacuser" --password="lacpassword" laconica < db/carrier.sql
306 This will populate your database with a list of wireless carriers
307 that support email SMS gateways.
309 2. Make sure the maildaemon.php file is executable:
311 chmod +x scripts/maildaemon.php
313 Note that "daemon" is kind of a misnomer here; the script is more
314 of a filter than a daemon.
316 2. Edit /etc/aliases on your mail server and add the following line:
318 *: /path/to/laconica/scripts/maildaemon.php
320 3. Run whatever code you need to to update your aliases database. For
321 many mail servers (Postfix, Exim, Sendmail), this should work:
325 You may need to restart your mail server for the new database to
328 4. Set the following in your config.php file:
330 $config['mail']['domain'] = 'yourdomain.example.net';
332 At this point, post-by-email and post-by-SMS-gateway should work. Note
333 that if your mail server is on a different computer from your email
334 server, you'll need to have a full installation of Laconica, a working
335 config.php, and access to the Laconica database from the mail server.
340 XMPP (eXtended Message and Presence Protocol, http://xmpp.org/) is the
341 instant-messenger protocol that drives Jabber and GTalk IM. You can
342 distribute messages via XMPP using the system below; however, you
343 need to run the XMPP incoming daemon to allow incoming messages as
346 1. You may want to strongly consider setting up your own XMPP server.
347 Ejabberd, OpenFire, and JabberD are all Open Source servers.
348 Jabber, Inc. provides a high-performance commercial server.
350 2. You must register a Jabber ID (JID) with your new server. It helps
351 to choose a name like "update@example.com" or "notice" or something
352 similar. Alternately, your "update JID" can be registered on a
353 publicly-available XMPP service, like jabber.org or GTalk.
355 Laconica will not register the JID with your chosen XMPP server;
356 you need to do this manually, with an XMPP client like Gajim,
357 Telepathy, or Pidgin.im.
359 3. Configure your site's XMPP variables, as described below in the
360 configuration section.
362 On a default installation, your site can broadcast messages using
363 XMPP. Users won't be able to post messages using XMPP unless you've
364 got the XMPP daemon running. See 'Queues and daemons' below for how
365 to set that up. Also, once you have a sizable number of users, sending
366 a lot of SMS, OMB, and XMPP messages whenever someone posts a message
367 can really slow down your site; it may cause posting to timeout.
372 You can send *all* messages from your microblogging site to a
373 third-party service using XMPP. This can be useful for providing
374 search, indexing, bridging, or other cool services.
376 To configure a downstream site to receive your public stream, add
377 their "JID" (Jabber ID) to your config.php as follows:
379 $config['xmpp']['public'][] = 'downstream@example.net';
381 (Don't miss those square brackets at the end.) Note that your XMPP
382 broadcasting must be configured as mentioned above. Although you can
383 send out messages at "Web time", high-volume sites should strongly
384 consider setting up queues and daemons.
389 Some activities that Laconica needs to do, like broadcast OMB, SMS,
390 and XMPP messages, can be 'queued' and done by off-line bots instead.
391 For this to work, you must be able to run long-running offline
392 processes, either on your main Web server or on another server you
393 control. (Your other server will still need all the above
394 prerequisites, with the exception of Apache.) Installing on a separate
395 server is probably a good idea for high-volume sites.
397 1. You'll need the "CLI" (command-line interface) version of PHP
398 installed on whatever server you use.
400 2. If you're using a separate server for queues, install Laconica
401 somewhere on the server. You don't need to worry about the
402 .htaccess file, but make sure that your config.php file is close
403 to, or identical to, your Web server's version.
405 3. In your config.php files (both the Web server and the queues
406 server!), set the following variable:
408 $config['queue']['enabled'] = true;
410 4. On the queues server, run the command scripts/startdaemons.sh. It
411 needs as a parameter the install path; if you run it from the
412 Laconica dir, "." should suffice.
414 This will run six (for now) queue handlers:
416 * xmppdaemon.php - listens for new XMPP messages from users and stores
417 them as notices in the database.
418 * jabberqueuehandler.php - sends queued notices in the database to
419 registered users who should receive them.
420 * publicqueuehandler.php - sends queued notices in the database to
421 public feed listeners.
422 * ombqueuehandler.php - sends queued notices to OpenMicroBlogging
423 recipients on foreign servers.
424 * smsqueuehandler.php - sends queued notices to SMS-over-email addresses
426 * xmppconfirmhandler.php - sends confirmation messages to registered
429 Note that these queue daemons are pretty raw, and need your care. In
430 particular, they leak memory, and you may want to restart them on a
431 regular (daily or so) basis with a cron job. Also, if they lose
432 the connection to the XMPP server for too long, they'll simply die. It
433 may be a good idea to use a daemon-monitoring service, like 'monit',
434 to check their status and keep them running.
436 All the daemons write their process IDs (pids) to /var/run/ by
437 default. This can be useful for starting, stopping, and monitoring the
443 Sitemap files (http://sitemaps.org/) are a very nice way of telling
444 search engines and other interested bots what's available on your site
445 and what's changed recently. You can generate sitemap files for your
448 1. Choose your sitemap URL layout. Laconica creates a number of
449 sitemap XML files for different parts of your site. You may want to
450 put these in a sub-directory of your Laconica directory to avoid
451 clutter. The sitemap index file tells the search engines and other
452 bots where to find all the sitemap files; it *must* be in the main
453 installation directory or higher. Both types of file must be
454 available through HTTP.
456 2. To generate your sitemaps, run the following command on your server:
458 php scripts/sitemap.php -f index-file-path -d sitemap-directory -u URL-prefix-for-sitemaps
460 Here, index-file-path is the full path to the sitemap index file,
461 like './sitemapindex.xml'. sitemap-directory is the directory where
462 you want the sitemaps stored, like './sitemaps/' (make sure the dir
463 exists). URL-prefix-for-sitemaps is the full URL for the sitemap dir,
464 typically something like 'http://example.net/mublog/sitemaps/'.
466 You can use several methods for submitting your sitemap index to
467 search engines to get your site indexed. One is to add a line like the
468 following to your robots.txt file:
470 Sitemap: /mublog/sitemapindex.xml
472 This is a good idea for letting *all* Web spiders know about your
473 sitemap. You can also submit sitemap files to major search engines
474 using their respective "Webmaster centres"; see sitemaps.org for links
486 Configuration options
487 =====================
489 The sole configuration file for Laconica (excepting configurations for
490 dependency software) is config.php in your Laconica directory. If you
491 edit any other file in the directory, like lib/common.php (where most
492 of the defaults are defined), you will lose your configuration options
493 in any upgrade, and you will wish that you had been more careful.
495 Almost all configuration options are made through a two-dimensional
496 associative array, cleverly named $config. A typical configuration
499 $config['section']['option'] = value;
501 For brevity, the following documentation describes each section and
507 This section is a catch-all for site-wide variables.
509 name: the name of your site, like 'YourCompany Microblog'.
510 server: the server part of your site's URLs, like 'example.net'.
511 path: The path part of your site's URLs, like 'mublog' or '/'
513 fancy: whether or not your site uses fancy URLs (see Fancy URLs
514 section above). Default is false.
515 logfile: full path to a file for Laconica to save logging
516 information to. You may want to use this if you don't have
518 locale_path: full path to the directory for locale data. Unless you
519 store all your locale data in one place, you probably
520 don't need to use this.
521 language: default language for your site. Defaults to US English.
522 languages: A list of languages supported on your site. Typically you'd
523 only change this if you wanted to disable support for one
525 "unset($config['site']['languages']['de'])" will disable
527 theme: Theme for your site (see Theme section). Two themes are
528 provided by default: 'default' and 'stoica' (the one used by
529 Identi.ca). It's appreciated if you don't use the 'stoica' theme
530 except as the basis for your own.
531 email: contact email address for your site. By default, it's extracted
532 from your Web server environment; you may want to customize it.
533 broughtbyurl: name of an organization or individual who provides the
534 service. Each page will include a link to this name in the
535 footer. A good way to link to the blog, forum, wiki,
536 corporate portal, or whoever is making the service available.
537 broughtby: text used for the "brought by" link.
538 timezone: default timezone for message display. Users can set their
539 own time zone. Defaults to 'UTC', which is a pretty good default.
540 closed: If set to 'true', will disallow registration on your site.
541 This is a cheap way to restrict accounts to only one
542 individual or group; just register the accounts you want on
543 the service, *then* set this variable to 'true'.
548 By default, Laconica sites log error messages to the syslog facility.
549 (You can override this using the 'logfile' parameter described above).
551 appname: The name that Laconica uses to log messages. By default it's
552 "laconica", but if you have more than one installation on the
553 server, you may want to change the name for each instance so
554 you can track log messages more easily.
559 You can configure the software to queue time-consuming tasks, like
560 sending out SMS email or XMPP messages, for off-line processing. See
561 'Queues and daemons' above for how to set this up.
566 array('enabled' => false),
568 array('url' => 'http://creativecommons.org/licenses/by/3.0/',
569 'title' => 'Creative Commons Attribution 3.0',
570 'image' => 'http://i.creativecommons.org/l/by/3.0/88x31.png'),
572 array('backend' => 'mail',
575 array('blacklist' => array()),
577 array('server' => NULL),
579 array('localonly' => true),
581 array('server' => NULL),
583 array('enabled' => false,
584 'server' => 'INVALID SERVER',
587 'encryption' => true,
588 'resource' => 'uniquename',
589 'password' => 'blahblahblah',
590 'host' => NULL, # only set if != server
591 'debug' => false, # print extra debug info
592 'public' => array()), # JIDs of users who want to receive the public stream
594 array('dropoff' => 864000.0),
596 array('piddir' => '/var/run',
615 The primary output for
620 These are some myths you may see on the Web about Laconica.
621 Documentation from the core team about Laconica has been pretty
622 sparse, so some backtracking and guesswork resulted in some incorrect
625 - "Set $config['db']['debug'] = 5 to debug the database." This is an
626 extremely bad idea. It's a tool built into DB_DataObject that will
627 emit oodles of print lines directly to the browser of your users.
628 Among these lines will be your database username and password. Do
629 not enable this option on a production Web site for any reason.
631 - "Edit dataobject.ini with the following settings..." dataobject.ini
632 is a development file for the DB_DataObject framework and is not
633 used by the running software. It was removed from the Laconica
634 distribution because its presence was confusing. Do not bother
635 configuring dataobject.ini, and do not put your database username
636 and password into the file on a production Web server; unscrupulous
637 persons may try to read it to get your passwords.
639 Further information and Feedback
640 ================================
642 There are several ways to get more information and