summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorEvan Prodromou <evan@controlyourself.ca>2008-09-22 18:32:39 -0400
committerEvan Prodromou <evan@controlyourself.ca>2008-09-22 18:32:39 -0400
commita1434ee1cfc04c5f6af30738ec8610726e464570 (patch)
tree1a2cbba608056e1fa10cf23ba049f2d28fdda4de
parent2944989d8a9a55b4da952820c356af8d17051093 (diff)
finish the README file
darcs-hash:20080922223239-5ed1f-1d34d37c75b2fc321e00063a788e9ca0c8baa359.gz
-rw-r--r--README329
1 files changed, 281 insertions, 48 deletions
diff --git a/README b/README
index b394454ea..103a4574e 100644
--- a/README
+++ b/README
@@ -3,7 +3,7 @@ README
------
Laconica 0.6.0
-12 September 2008
+22 September 2008
This is the README file for Laconica, the Open Source microblogging
platform. It includes installation instructions, descriptions of
@@ -62,6 +62,25 @@ License along with this program, in the file "COPYING". If not, see
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
+================
+
+New features in version 0.6.0 include:
+
+* Invitations by email.
+* Users can mark messages as "favorites" (only Web, not API).
+* A bridge to push messages on the Laconica instance to an account on
+ Twitter.
+* Direct private messages between users on a server (only Web, not API
+ or IM or SMS).
+* Restructured off-line daemons.
+
Prerequisites
=============
@@ -84,6 +103,7 @@ 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.
For some functionality, you will also need the following extensions:
@@ -477,12 +497,96 @@ 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.
+
Upgrading
=========
+If you've been using Laconica 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. 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.
+
Configuration options
=====================
@@ -560,59 +664,139 @@ 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
-
- 'queue' =>
- array('enabled' => false),
- 'license' =>
- array('url' => 'http://creativecommons.org/licenses/by/3.0/',
- 'title' => 'Creative Commons Attribution 3.0',
- 'image' => 'http://i.creativecommons.org/l/by/3.0/88x31.png'),
- 'mail' =>
- array('backend' => 'mail',
- 'params' => NULL),
- 'nickname' =>
- array('blacklist' => array()),
- 'avatar' =>
- array('server' => NULL),
- 'public' =>
- array('localonly' => true),
- 'theme' =>
- array('server' => NULL),
- 'xmpp' =>
- array('enabled' => false,
- 'server' => 'INVALID SERVER',
- 'port' => 5222,
- 'user' => 'update',
- 'encryption' => true,
- 'resource' => 'uniquename',
- 'password' => 'blahblahblah',
- 'host' => NULL, # only set if != server
- 'debug' => false, # print extra debug info
- 'public' => array()), # JIDs of users who want to receive the public stream
- 'tag' =>
- array('dropoff' => 864000.0),
- 'daemon' =>
- array('piddir' => '/var/run',
- 'user' => false,
- 'group' => false)
- );
-Web
----
+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.
-Mail
+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
----
-SMS
----
+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
-XMPP
+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.
+
+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.
+
+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.
+
Troubleshooting
===============
-The primary output for
+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.
Myths
=====
@@ -636,11 +820,60 @@ assumptions.
and password into the file on a production Web server; unscrupulous
persons may try to read it to get your passwords.
-Further information and Feedback
-================================
+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:
-There are several ways to get more information and
+ 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.
+* 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)
+
+Thanks also 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.