/docs/INSTALL.pod
Perl | 1774 lines | 1425 code | 331 blank | 18 comment | 94 complexity | 1bf6a9413075236fa35bcda4fdcaacb2 MD5 | raw file
Possible License(s): GPL-2.0
Large files files are truncated, but you can click here to view the full file
- #!perl -w
- # To check its syntax, run this document through perl.
- # To make it into plaintext at the standard location:
- # perldoc -tF docs/INSTALL.pod > INSTALL
- use Pod::Checker;
- podchecker(\*DATA);
- __END__
- =head1 NAME
- INSTALL - Slash Installation
- =head1 SYNOPSIS
- This document describes how to install Slash, versions 2.2 and
- pre-releases of 2.3 and 2.5. For instructions on installation or upgrade
- of previous versions of Slash, see the INSTALL document included with
- those distributions.
- These instructions have only been tested on Linux. Installation under
- BSD and other Unix OSes is doable, with minor glitches (see L<"BSD
- Systems"> below). Windows is not supported.
- Slash can always be downloaded from SourceForge.net, from the FTP site,
- and via CVS.
- http://sf.net/projects/slashcode/
- ftp://ftp.slashcode.com//pub/slashcode/
- http://cvs.slashcode.com/
- See the SourceForge.net page for patches and bug reports.
- =head2 Which version should I use?
- First of all: if you are using Slash 2.2.5 or before, including all 2.1.x,
- 2.0.x, and 1.x versions, you should upgrade to the latest version in
- the 2.2 tree, 2.2.6, as soon as possible. There are security issues
- with previous versions. You should not install previous versions.
- As of this writing (August 2006), our last official release (2.2.6) was
- long ago, and many features have been added since. All development has
- been in CVS. If you are installing a new Slash site, you don't want to
- use 2.2.6. And while you probably don't want to use the very latest
- CVS, you almost certainly do want to use the latest "R_" tag available
- in CVS. See L<"VERSIONS">, "CVS tags", below, for advice on choosing
- and maintaining a CVS installation.
- =head2 Read, then install
- We know you want to get right into the installation, but you must first
- read, carefully, these sections of this INSTALL file:
- =over 4
- =item *
- REQUIREMENTS, to make sure you have the right hardware and software
- =item *
- "CVS tags," in VERSIONS, to make sure you have the right version
- of this code
- =item *
- SECURITY NOTES, to keep your system safe
- =item *
- INSTALLATION (the longest section), to make sure you will be able to
- finish what you start
- =back
- And it's a good idea to at least skim:
- =over 4
- =item *
- INSTALLATION OPTIONS
- =item *
- TROUBLESHOOTING
- =back
- Read those sections before you begin actually performing the steps in
- L<"INSTALLATION">.
- This document also contains information on upgrading a Slash site
- (which can be tricky), and uninstalling (which is easy).
- =head2 Updates to this file
- This INSTALL file you are currently reading may not be the latest.
- Again, you probably don't want to upgrade your whole Slash checkout to
- the very latest CVS. But if you encounter problems, it might not be
- a bad idea to look over the very latest version of this INSTALL file,
- which you can find at:
- L<http:E<sol>E<sol>slashcode.cvs.sourceforge.netE<sol>*checkout*E<sol>slashcodeE<sol>slashE<sol>INSTALL>
- The version of this file that you are currently reading is:
- $Id$
- If there are more recent versions of this file, you can find a list of
- those changes at:
- L<http:E<sol>E<sol>slashcode.cvs.sourceforge.netE<sol>slashcodeE<sol>slashE<sol>INSTALL>
- =head1 INSTALLATION
- =head2 Installation Note
- All of the installation steps below should be executed as root. If this
- is a problem, then Slash is probably not for you (see "Non-Root" below,
- under "INSTALLATION OPTIONS"). Type carefully. Now's a good time to
- back up anything important.
- =head2 Installation Procedure
- There are eight steps to installation. Anything already done can be
- skipped -- but only if you have the correct version and configuration,
- particularly with Apache/mod_perl.
- =over 4
- =item 1.
- B<Install MySQL.>
- If it is already installed, doublecheck that its version is at least the
- minimum required (see L<"REQUIREMENTS">). If you have questions about
- the installation process, please refer to MySQL documentation.
- Slash requires that your MySQL server run in the GMT timezome. Find your
- global my.cnf file (probably C</etc/my.cnf> or C</etc/mysql/my.cnf>),
- locate the C<[mysqld_safe]> (or C<[safe_mysqld]>) group, and add this line
- to it:
- timezone = GMT
- Start MySQL (it must be running for the installation of Slash and some
- perl modules). Or, if it is already running, restart MySQL (if you have
- other services using MySQL, you should probably stop and start them --
- make sure they are timezone-agnostic!).
- Create a database to be used by Slash. Our default name is 'slash':
- CREATE DATABASE slash;
- Create a username/password that can access that database, and ensure
- that user has at least privileges to select, insert, update, delete,
- lock, create, drop, index and alter. For example, if your whole site
- (slashd daemon and apache) will run on the same machine as your mysql
- server, and you wanted to use the mysql username 'slash', you might:
- GRANT SELECT, INSERT, UPDATE, DELETE, LOCK TABLES, CREATE, DROP,
- INDEX, ALTER ON slash.* TO 'slash'@'localhost'
- IDENTIFIED BY (quoted password);
- GRANT PROCESS ON *.* TO 'slash'@'localhost' IDENTIFIED BY
- (quoted password);
- In this case, 'slash' would also be the name of your MySQL user as
- described in L<"Types of Users"> below. You'll have to give your MySQL
- user to DBIx::Password when you install and configure it, so don't
- forget it.
- =item 2.
- B<Install perl.>
- Perl is likely already installed on your machine; doublecheck that its
- version is at least the minimum required (see L<"REQUIREMENTS">).
- Also, check the "Libraries" (or "Debian libraries") section under
- L<"REQUIREMENTS">, below. You may need to install dev packages for not
- only perl but mysql and expat as well and now's a good time to take care
- of that.
- =item 3.
- B<Install Apache and mod_perl.>
- B<You MUST install mod_perl and Apache as directed here>. OK, that is
- not strictly true, but unless you really know what you're doing,
- just assume it's true. If you already have mod_perl installed,
- it is probably not configured properly to work with Slash and
- you will have to rebuild it.
- If you are using the provided httpd.conf file from the slash
- distribution, and find that Apache is giving you errors, chances
- are mod_perl is not installed correctly, and you need to build
- it from scratch. Not following this direction is one of the most
- common reasons we see for a Slash install not working.
- Of course, if you have your own Apache modules or build options,
- you will need to modify the instructions here appropriately.
- First, untar apache and mod_perl. Then, go to the mod_perl directory,
- and have mod_perl build and install apache for you:
- perl Makefile.PL APACHE_SRC=../where_you_have_apache/src \
- DO_HTTPD=1 USE_APACI=1 PERL_MARK_WHERE=1 EVERYTHING=1 \
- APACHE_PREFIX=/where_apache_will_be_installed
- make
- make test
- make install
- B<NOTE>: You may be unsuccessful with C<make test> if the perl modules
- are not yet installed. However, some perl modules will not install
- without Apache and mod_perl installed. If you wish, skip C<make test>,
- run C<make install>, install the perl modules in step 4, and then come
- back and run C<make test> here again to make sure everything is OK.
- B<NOTE>: If you know what you're doing, Slash will work with a DSO
- Apache. Be sure you're on the latest versions of Apache and
- mod_perl and remember PERL_MARK_WHERE=1 and EVERYTHING=1.
- B<NOTE>: See also "Other requirements" under L<"REQUIREMENTS">.
- B<Ubuntu NOTE>: In mid-2006 Ubuntu 6.x switched sh to point to dash
- instead of bash, which apparently breaks the above step (because dash's
- 'echo -E' isn't compliant enough for apache's 'configure'). We're looking
- into it, but for now apparently (temporarily) linking /bin/sh to /bin/bash
- during this step is a workaround.
- L<https:E<sol>E<sol>launchpad.netE<sol>ubuntuE<sol>+spec/dash-as-bin-sh>
- (Update: this appears to no longer be a problem, but if you encounter
- problems on Ubuntu, check where your /bin/sh points.)
- =item 4.
- B<Install the perl modules.>
- Slash is powerful and complex, and, rather than reinvent the wheel, it
- often relies on CPAN modules. Open-source code reuse has many advantages.
- One disadvantage is that installing all those modules can be tricky,
- as you may be about to find out.
- You could install each module in F<Bundle/Slash.pm> by hand, but this
- would be time-consuming. Instead, you'll want to install the bundle
- C<Bundle::Slash> using CPAN.
- =over 4
- B<IMPORTANT NOTES (read through these first! really!)>:
- =over 4
- =item B<Overall comment about CPAN module failure>
- It is possible that upon typing "install Bundle::Slash", you will have
- one or more modules fail to install on the first try. The rest of the
- modules will be successfully installed but some won't. In that case
- you will want to fix the problems and retype "install Bundle::Slash"
- to make sure everything proceeds smoothly. Once that command gives you
- just a long list of "Foo::Bar is up to date," you are done. Until that
- point, you are not done; you must resolve the errors.
- =item B<Old Version of Bundle::Slash>
- If you have previously installed Bundle::Slash, you will want
- to install it again, but you will need to delete the existing
- version. Go to your F<.cpan/Bundle> directory (usually
- F<~/.cpan/Bundle/>) and remove F<Slash.pm>.
- =item B<Overactive CPAN>
- With some versions of the CPAN module, the module will try to
- download and install the latest version of perl. Watch what
- the module is doing; if it begins to download an entire perl
- distribution, interrupt it (hit ctrl-C) until it stops, then try
- again with the CPAN module. This should not be an issue in the latest
- version of Bundle::Slash.
- =item B<Uninstalling Old Modules>
- Sometimes, you will be installing a newer version of a module that exists
- elsewhere on the system. You probably want to tell the CPAN module to
- automatically remove older files. To do that from the CPAN shell, type:
- cpan> o conf make_install_arg UNINST=1
- And if you want that to be CPAN's default from now on, add:
- cpan> o conf commit
- =item B<Automatically Installing Dependencies>
- Some of the modules in Bundle::Slash require other modules. We have
- not put some of those other modules in Bundle::Slash because, if those
- requirements change in the future, we don't want to make future Slash
- sites install more than they have to.
- If you see this:
- ---- Unsatisfied dependencies detected during [FOO/Bar-1.23.tar.gz] -----
- Foobar::Baz
- Shall I follow them and prepend them to the queue
- of modules we are processing right now? [yes]
- That's normal; just hit return.
- If it annoys you to have to do this, edit the C<prerequisites_policy>
- field of your CPAN/Config.pm file. Or, just do this to change it to
- automatically follow dependencies and commit the change:
- cpan> o conf prerequisites_policy follow
- cpan> o conf commit
- =item B<Data::JavaScript::Anon>
- There are bugs in versions earlier than 1.00 that break our JS. Unfortunately,
- CPAN seems to prefer version 0.9 even though 1.00 is available. You may
- have to install a better version in CPAN by hand:
- cpan> install A/AD/ADAMK/Data-JavaScript-Anon-1.00.tar.gz
- =item B<Additional Libraries>
- You must have certain libraries existing on your system before building,
- for Compress::Zlib, XML::Parser, DBI and DBD::mysql. See "Libraries"
- under L<"REQUIREMENTS">, below.
- =item B<BSD Systems>
- If running BSD, also install the BSD::Resource module. We have heard
- reports of minor problems running Slash on BSD, but you are welcome
- to try. See SLASH_PREFIX below, and after the install, doublecheck
- the init scripts. If you have to make changes to get it to work, send
- us patches or detailed bug reports please: we want to support the BSDs.
- =item B<DBIx::Password>
- When installing DBIx::Password, you will be asked for various
- information, the same information used to create the database
- and database user in Step 1. First, you'll be asked for a
- B<virtual user> name, which will be the identifier for all of
- this data. You can just use the name of your site,
- or any other alphanumeric string. This string will be your
- "DBIx::Password virtual user" as described in L<"Types of Users"> below --
- you will use this in other places, so don't forget it.
- Then you'll be asked for your DBI driver (mysql), the name of the database
- you CREATEd in Step 1, its machine (maybe 'localhost' or an IP number) and
- port, and then the MySQL user name you GRANTed privileges to in Step 1
- and its password.
- Some perl modules you can hit return for defaults and they'll work.
- This isn't one of them. If you don't understand what you're doing here,
- don't fake it -- that's a common reason for Slash installations failing.
- =item B<Documentation>
- To read the README for any module, before or after installing:
- cpan> readme MODULE
- To read the documentation of any of the modules, once they have been
- installed, type C<perldoc MODULE> at the command line.
- See L<perlmodinstall> for more information on installing perl modules.
- =back
- =back
- Now that you have read the above notes, you're ready to install the
- perl modules.
- To use the CPAN module, invoke the CPAN shell:
- perl -MCPAN -e shell
- (Or, you may have the program "cpan" already available, which
- does the same thing.)
- If this is the first time you've invoked CPAN, you will be asked to
- configure it. Note that CPAN works best if most or all of these helper
- programs are installed: bzip2 gzip tar unzip make curl lynx wget ncftpget
- ncftp ftp gpg. If your OS installation is very anemic and you lack most
- of them, you might ^C its questions, install the missing programs, and
- then re-invoke the CPAN shell to restart configuration.
- It's probably a good idea here to install the latest version of the CPAN
- module itself, along with all the helper modules it requires. This is
- an optional step but may make the rest of module installation easier:
- cpan> install Bundle::CPAN
- If you chose to do that, then afterwards, C<exit> the CPAN and reinvoke it.
- (The plain shell command "cpan" will probably now work.)
- Next, install some important networking modules. This is also optional
- but, if there are problems with these modules, you'll want to resolve
- them before moving on to the rest of the installation:
- cpan> install Bundle::LWP
- Make sure all those modules are installed and up to date before
- proceeding. Note that Net::Cmd has a history of being a little broken
- in its tests; if it fails on tests 8 and 9 of t/require, then it's OK;
- just do C<force install Net::Cmd> and repeat C<install Bundle::LWP>.
- On Mac OS X and possibly other operating systems, if LWP's live/https
- tests fail, C<install Net::SSL> manually and retry.
- Assuming you chose to install the LWP, then after it's been configured
- successfully, again, C<exit> the CPAN and reinvoke it.
- Finally, you must install Bundle::Slash:
- cpan> install Bundle::Slash
- This will be a long process. Several modules will ask to be configured
- during this process. Here are some tips:
- =over 4
- =item B<DBI>
- Don't worry about the threading warning. Slash doesn't use threads.
- =item B<DBIx::Password>
- See "DBIx::Password" under IMPORTANT NOTES above.
- =item B<Apache::Test> and B<Apache::Cookie>
- You will need C<httpd> and C<apxs> in your $PATH, and even if they
- are there, you will probably see the lengthy error that starts "Apache
- cannot spawn child processes as 'root'". This is because, ironically,
- Apache::Test's self-tests are a colossal pain to actually run (I take
- the option to skip them). And personally I just C<force install
- Apache::Cookie> which is lame but solves the problem.
- =item B<Template>
- The Template Toolkit is a complex install. Try accepting all the
- defaults and see if it works. It has 90 test scripts with over 2000
- tests, and installation will be halted if just 1 of these tests fails.
- Do a C<look Template> and try your best to resolve the issues.
- The F<README> includes a URL to the mailing list archives, where you
- may find help. If you're getting 100 errors, you need to fix them,
- but if you're down to 1 or 2 you can't fix, you might just make a note
- of what the failures were and just C<force install Template>.
- =item B<Other failures>
- We can't predict whether bugs will appear in CPAN modules in future.
- Often the bugs are not in the software proper, but in its too-strictly
- coded test suites, which don't allow for changed but still-legitimate
- output. When this happens, the module itself is fine but it will not
- install unless forced. As of October 2006, we've noticed the following
- module throw spurious errors, requiring a C<force install>:
- HTML::CalendarMonth 1.18
- =back
- If you have problems, feel free to re-run C<install Bundle::Slash>. It
- will safely skip anything already installed.
- Again: once you are able to do C<install Bundle::Slash> and see nothing
- but a long list of modules that are "up to date," you are done. Until you
- see that, you are not done with this step!
- If you wish to take full advantage of Slash, there are some plugins
- not installed and vars not turned on by default, which provide
- additional features, improve performance, or help in testing, which
- require additional perl modules and sometimes non-perl libraries.
- See the listing at the bottom of Bundle/Slash.pm, and see also the
- tips in plugins/Admin/README, plugins/HumanConf/INSTALL-NOTES, and
- plugins/Stats/README.
- =item 5.
- B<Install Slash.>
- Unpack the distribution, go to the new directory that
- creates, and type:
- make
- make install
- B<Note>: you will want the GNU versions of fileutils and make. Older
- versions of install, and make and cp from other systems, might not work.
- There are a few options to C<make> and C<make install> you may
- want to change.
- option default purpose
- ==========================================================
- SLASH_PREFIX /usr/local/slash Location for
- installed files
- INIT /etc or /etc/rc.d Location for init
- scripts
- USER nobody User to own files
- GROUP nobody Group to own files
- CP cp Name of or path to
- alternate 'cp'
- INSTALL install Name of or path to
- alternate 'install'
- (USER and GROUP can also be changed later on a per-site basis,
- in step 6, while running C<install-slashsite>.)
- So, for example, you might type (although the default SLASH_PREFIX
- is I<strongly> recommended):
- make SLASH_PREFIX=/home/slash
- make install SLASH_PREFIX=/home/slash
- When done, a configuration file for Apache will be created at
- F<$SLASH_PREFIX/httpd/slash.conf>. You can put its contents into your
- httpd.conf, or you can just C<Include> it in your httpd.conf. You
- must do one or the other!
- B<WARNING!>
- Please be aware that if you include F<$SLASH_PREFIX/slash.conf>
- or F<$SLASH_PREFIX/sites/sitename/sitename.conf> more than once,
- or if this file shares contents with directives in httpd.conf,
- that your Slash site WILL break. The directives in
- F<$SLASH_PREFIX/slash.conf> should be run only ONCE in any any
- site context. Read through F<$SLASH_PREFIX/slash.conf> to make
- sure it all looks proper.
- =item 6.
- B<Install your Slash site.>
- At this point, you may want to (re)read L<"DBIx::Password"> in L<"SECURITY
- NOTES"> at the end of this section, and consider the option of installing
- your site with a custom unix system user and group for added security.
- You will be prompted for user and group shortly.
- Go to your installation directory (by default, F</usr/local/slash>)
- and execute (where C<VIRTUAL_USER> is the name of the virtual
- user given in the DBIx::Password distribution):
- bin/install-slashsite -u VIRTUAL_USER
- The program will prompt for answers to several configuration questions.
- Then it will install your site.
- Another configuration file will be created at
- F<$SLASH_PREFIX/$SITENAME/$SITENAME.conf>, which will be C<Include>'d
- in F<$SLASH_PREFIX/httpd/slash.conf>. You'll want to add an C<Include>
- for the latter in your Apache's F<httpd.conf> if you haven't done so on
- a previous site install.
- If you are using virtual hosting by hostname, you may also need to add
- a NameVirtualHost.
- If you don't have your Slash site in the root of the web server
- (e.g., L<http:E<sol>E<sol>www.example.comE<sol>mysiteE<sol>> instead
- of the more usual L<http:E<sol>E<sol>www.example.comE<sol>>), you
- will need to adjust the rootdir, rdfimage, imagedir, absolutedir,
- and cookiepath variables, and you also need to change your Apache
- config appropriately. If you're planning on having sections with
- more than two dots in the hostname (e.g. your mainpage will be at
- L<http:E<sol>E<sol>division.company.comE<sol>> with a section at
- L<http:E<sol>E<sol>newprojects.division.company.comE<sol>>) you will
- also want to set the cookiedomain var (e.g. to .division.company.com).
- These are all in the vars table of your database.
- B<NOTE>: Read the message printed at the end of running install_slashsite.
- Failure to pay attention here is another common reason we see for Slash
- installations not working.
- B<Ubuntu NOTE>: Reported after installing on Kubuntu 7.10, a Slash install's
- idea of run-levels was not sufficient to start slashd at boot. The following
- makes sure that all the right run-levels are covered, and that rebuilding
- Slash won't mistakenly double-start the daemon:
- sudo update-rc.d -f slash remove
- sudo update-rc.d slash defaults
- sudo mv /etc/rc3.d/S*slash /etc/rc3.d/S99slash
- sudo mv /etc/rc6.d/K*slash /etc/rc6.d/K99slash
- =item 7.
- B<Start it up.>
- After installation of the site is done, you'll need to start Apache.
- Stop it if necessary, then start it:
- apachectl stop
- apachectl start
- Use the apachectl script under the APACHE_PREFIX you specified in step 3.
- Don't try its "restart" or "graceful" options, you'll need to do a full
- stop and start.
- Then run slashd. This should be done via the init script:
- /etc/init.d/slash start
- slashd is the daemon that runs routine maintenance on Slash sites,
- including sending out daily mailings, cleaning up the database,
- and updating stories. The init script above will start up an
- individual slashd daemon process for each installed site (and while
- running, they will spawn child processes, some of which may run for a
- long time or until you stop slashd with "slash stop").
- Now's a good time to (re)read the L<"SECURITY NOTES"> section at the
- end of this file.
- =item 8.
- B<Stay in touch.>
- For as long as you are running a Slash site, you should stay on our
- "slashcode-announce" mailing list, to receive notification of security
- issues (and, rarely, other major news of interest to Slash admins).
- You can sign up at:
- https://lists.sourceforge.net/lists/listinfo/slashcode-announce
- You may wish to subscribe to "slashcode-general", for discussion of
- running Slash sites. This list probably averages 1-2 emails a day,
- mostly on administration issues, and bugs and features in Slash.
- https://lists.sourceforge.net/lists/listinfo/slashcode-general
- You may also wish to create a user on slashcode.com and subscribe to
- its daily newsletter. If/when news is posted to that site, you'll be
- in the loop.
- If you want to register your new site, feel free to do so at
- L<http:E<sol>E<sol>slashcode.comE<sol>sites.pl>.
- =back
- =head1 INSTALLATION OPTIONS
- =head2 Multiple Servers
- You can, of course, have a separate database server from your Slash
- server. Further, you can have multiple web servers for one Slash site,
- and a good thing too because web server RAM/CPU will probably be your
- first bottleneck as your site grows.
- Slashdot has one primary server with all of the code (Apache, perl,
- etc.) in /usr/local. That server runs slashd and NFS. Our slashd writes
- directly to its /usr/local/slash. Each web server mounts /usr/local
- read-only over NFS. (Yes, NFS has a reputation for being flaky, but
- we've never had a problem with it, which we attribute both to good
- sysadmins and to only exporting our filesystem read-only.)
- Some notes:
- =over 4
- =item *
- Make sure the MySQL server allows the user to log in from each web
- server, and the slashd server.
- =item *
- Make sure, if you use the same httpd tree on all machines, that
- the httpd.conf is listening to the proper IP addresses. This can be
- done by putting all of the IP addresses in the conf file, or by having
- a separate Listen file on each machine. Similarly, make sure that
- each web server's logfiles are unique to each machine, not written to the
- NFS volume.
- =back
- =head2 Virtual Hosts
- Slash has support for virtual hosts, so you can have multiple
- Slash sites on one machine. Simply execute step 6 in the install
- process for each Slash site (after adding a new virtual user to
- DBIx::Password for each).
- =head2 SSL
- In Slash, there are two variables for the root URL of the site.
- B<absolutedir> is the full URL, including protocol, while B<rootdir>
- is the URL without protocol:
- absolutedir http://slashcode.com
- rootdir //slashcode.com
- B<absolutedir> is used only for creating external links to the site
- (such as in RSS files). B<rootdir> is used for internal links; that
- way, you can use the same HTML pages for SSL and non-SSL. You don't
- have to do anything special to the code or preferences to allow it to
- work with SSL by itself, SSL and non-SSL together, or non-SSL by itself.
- =head2 Non-Root
- It is theoretically possible to install and run everything here without
- root.
- It is not easy. If you don't know your flavor of unix intimately, we
- don't recommend trying this.
- Describing the process for a non-root install would take up significant
- space and time, having to account for differences in various systems,
- and all the workarounds necessary for it to work. We don't support it,
- and we're not going to document it.
- If you must have a non-root install, consult the various documentation
- for Apache, MySQL, and perl about running and installing without root
- access. Then, for Slash, you need to set the make variables PREFIX,
- SLASH_PREFIX, and INIT appropriately for your needs.
- B<Note>: Slash sites (or, more accurately, Apache + mod_perl and MySQL) take
- up a lot of system resources. It is I<not advisable> for anyone to
- run Slash on any system, without the permission of the administrator
- of that system.
- =head2 Memcached
- Memcached is not required, but Slash includes optimizations that move
- load from your (expensive) MySQL server to a (very cheap) memcached
- server or servers. If you are concerned about performance, this is one
- of the first options to install. You can probably install it
- using your operating system's package management, and/or see
- L<http:E<sol>E<sol>www.danga.comE<sol>memcachedE<sol>>.
- A 64 or 128 MB memcached instance should be plenty for moderate-sized
- Slash sites. Just set the vars 'memcached', 'memcached_keyprefix', and
- 'memcached_servers', and restart apache and slashd. That's it.
- (As of August 2006, Slashdot uses a total of 2 GB of memcached, but
- that's in small allocations spread across many servers because we like
- redundancy. Last I checked the 2 GB wasn't even half full.)
- =head2 Separate Image Server
- Those of you with infinite RAM will have no problems hosting as many Slash
- sites as you want on a single box running just Apache. Those whose RAM
- is limited may be able to keep your MaxClients down to a reasonable level
- to avoid going into swap, and still not lock clients out of your website,
- by using a separate webserver process to deliver your images.
- This is possible with any website, of course, not just a Slash site, but
- because Slash's httpd clients all have mod_perl, a lot of perl modules,
- and a lot of templates all compiled into RAM, they are especially heavy.
- While serving an image may take only a few milliseconds, which would you
- rather have tied up on your computer for those milliseconds, 25 MB of RAM
- or 5 MB?
- Slashdot, and some other Slash sites we're hosting, are currently using
- boa 0.94.14rc17 (L<http:E<sol>E<sol>www.boa.orgE<sol>>) for images.
- Boa is fast and has a small footprint. It's easy to build
- (C<./configure && make>) but you have to install it yourself by
- copying the binary and mkdir'ing a little tree wherever you want it.
- We did roughly this. Your mileage may vary. This sets up an alternate
- server just for images on port 8080, and sets Slash's imagedir var to
- point to it. Your apache will still serve images at the old URLs if
- anyone requests them, but nobody will, because your site's pages will
- all point to boa:
- # Install boa and set up its files.
- cd /usr/local/src/boa-0.94.14rc17
- ./configure && make
- mkdir /usr/local/boa
- mkdir /usr/local/boa/bin
- mkdir /usr/local/boa/htdocs
- cp -a src/{boa,boa_indexer,webindex.pl} /usr/local/boa/bin/
- ln -s /usr/local/slash/site/mysite/htdocs/images /usr/local/boa/htdocs/images.mysite.com
- touch /usr/local/boa/htdocs/favicon.ico
- # Set up and edit boa conf file.
- cp examples/boa.conf /usr/local/boa/
- # At this point we patched /usr/local/boa/boa.conf, changing
- # Port to 8080, ServerName to www.mysite.com, DocumentRoot to
- # /usr/local/boa/htdocs, and commenting out the DirectoryIndex,
- # DirectoryMaker, Alias and ScriptAlias directives.
- # Start boa.
- /usr/local/boa/bin/boa
- # In mysql client:
- # UPDATE vars SET value='//www.mysite.com:8080/images.mysite.com' WHERE name='imagedir';
- # INSERT IGNORE INTO story_dirty SELECT stoid FROM stories WHERE in_trash='no';
- # Restart apache, slashd; let slashd rewrite .shtml files both
- # recent and archived.
- You'll probably also want to create a script in your init.d and rcN.d
- directories so boa runs at startup along with apache.
- =head1 UPGRADING
- B<Some of these upgrade procedures are still in testing. Please read
- them entirely before beginning. We are not responsible for any loss of
- data or functionality.>
- =head2 Slash 1.0 -E<gt> Slash 2.2
- You've got a site running Slash 1.0, from 2001? We're so sorry to
- hear that.
- Please read the complete documentation of F<utils/slash1toslash2.2>.
- We believe it will convert your database from Slash 1.0 to a new Slash
- 2.2 database, but it hasn't been tested in some time. The program
- documentation (which can be read with F<perldoc>) details exactly what
- process it follows to do the conversion, so you can attempt to do it by
- hand if you prefer.
- =head2 Slash 2.0 -> Slash 2.2
- Slash 2.2 is a major upgrade from Slash 2.0. It takes a little bit
- of work to get it going.
- =over 4
- =item 1.
- BACK EVERYTHING UP ON THE EXISTING SITE.
- =item 2.
- Install Bundle::Slash. If you have done so previously, follow
- the instructions for removing the existing version of
- Bundle::Slash before proceeding.
- =item 3.
- Apply this patch to your installed Slash::Install module (probably
- easiest to hand-edit the file):
- --- Install.pm~ Wed May 9 15:02:34 2001
- +++ Install.pm Fri Sep 28 12:44:41 2001
- @@ -116,7 +116,7 @@
- sub writeTemplateFile {
- my($self, $filename, $template) = @_;
- open(FILE, '>' . $filename) or die "$! unable to open file $filename to write to";
- - for (keys %$template) {
- + for (qw(section description title page lang name template seclev)) {
- next if ($_ eq 'tpid');
- print FILE "__${_}__\n";
- $template->{$_} =~ s/\015\012/\n/g;
- =item 4.
- Run C<template-check> on your site, and make a note of every change
- you've made to the standard templates. You will need to make those
- changes again, manually, later.
- This is unfortunately unavoidable, because templates include code
- that changes significantly between releases. It is recommended
- that you compile your changes into a THEME so they may easily be
- updated and applied.
- =item 5.
- Stop Apache and slashd on the target machine(s).
- =item 6
- Install Slash.
- B<If installing on a different machine ...>
- =over 4
- =item 1
- Install slash 2.2 as normal. Do not yet run C<install-slashsite>.
- =item 2
- Make sure that from this machine, you can access not only the database
- used for this installation, but the one used for the old installation.
- You may wish to, instead of accessing that database directly if it
- on another machine, dumping it and adding it to your new database server
- under a different name.
- =item 3
- Add a virtual user to DBIx::Password for the old installation.
- =back
- B<If installing on the same machine ...>
- =over 4
- =item 1
- Create a new database for the new installation. You cannot
- use the same database for both installations.
- =item 2
- Add a new virtual user to DBIx::Password for the new database,
- and update (and flush) MySQL privileges appropriately. You cannot
- use the same virtual user for both installations.
- =item 3
- It is highly recommended that you move F</usr/local/slash>
- (or whatever your installation directory is) to a new location,
- such as F</usr/local/slash-old>, and install a clean slash 2.2
- installation. However, this is not necessary to do; you may install
- slash 2.2 on top of the slash 2.0 installation.
- The reason to not move anything is that you can keep any customizations
- done (images, additional scripts and plugins, static files, etc.).
- The reason to move it is so that everything is clean. It is highly
- recommended that you move it, and then manually copy back the pieces
- you want.
- =item 4
- In any event, either move the old directory, or don't, and
- then install slash 2.2 as normal. Do not yet run C<install-slashsite>.
- =back
- =item 7.
- If you have plugins or themes from the old installation to install,
- copy them over now. Warning: some plugins and themes might need to be
- ported first. You may wish to deal with them later if they are not
- yet ported to slash 2.2.
- =item 8.
- Run C<install-slashsite>. Use the new virtual user.
- =item 9.
- Copy over any files (images, FAQs, etc.) that need to be copied, if necessary.
- =item 10.
- Run update script, F<utils/slash2toslash2.2>. B<Read its instructions!>
- =item 11.
- Update templates.
- =item 12.
- Doublecheck Apache configs (httpd/slash.conf, site/sitename/sitename.conf).
- These configs have changed from the last version. Read the comments and set
- them up as desired.
- =item 13.
- Start Apache.
- =item 14.
- Start slashd.
- =back
- =head2 Slash 2.2.x -> Slash 2.2.y
- Read all of this section before doing any of it.
- The first thing to do is to, as per the instructions below under
- INSTALLATION, unpack the latest distribution and run make and make
- install with the proper arguments.
- =over 4
- =item Overwriting Changes
- This process will overwrite any customizations of your installed
- modules, or customizations of the installed scripts in
- /usr/local/slash/themes/ and /usr/local/slash/plugins/ (for themes
- and plugins that come with Slash). If you ran C<install-slashsite>
- with the default option of using symlinks, and made customizations
- to the originals instead of breaking the symlink and copying the file
- over, then this will overwrite your changes.
- If you did modify the original instead of a copy, then break the
- symlink, copy over the original (as modified), and then continue.
- The original will be copied over by the new version, and your modified
- copy will remain intact.
- =item Templates
- With every update, there are changes to templates. But most people
- will modify their templates. A relatively simple way to see what
- has changed is to use template-tool and template-check. This
- procedure should help most users deal with the integration of new
- templates into an existing site (it will only work with the slashcode
- theme, but a simple modification to the code of template-check
- can fix that).
- =over 4
- =item Dump
- Use template-tool to dump your templates into an empty directory.
- % mkdir templates
- % cd templates
- % template-tool -u VIRTUAL_USER -d
- (Defaults to current directory.)
- =item Compare
- Use template-check to compare installed templates in
- /usr/local/slash/themes/slashcode/ and /usr/local/slash/plugins/ against
- the templates that have been dumped.
- % template-check -u VIRTUAL_USER
- (Defaults to current directory.)
- This will use diff to show you the differences. You can either go
- into the templates with a text editor (in another window) and change
- the dumped ones by hand, edit them by hand in the Template Editor
- via the web browser, or take a note of every template you want to
- copy over your existing template.
- After each directory of templates is done, hit "q" to continue to
- the next plugin/theme.
- =item Sync
- If you made changes by hand via the web, you are done. Otherwise, take
- the list of templates to update, and pass the full filenames to
- template-tool (this will either be the templates you modified by hand
- in the dump directory, or the unmodified ones in the installation
- directories). You might need to put each filename in quotes because of
- the ";" character in the filenames. This will overwrite your existing
- template with the new template.
- % template-tool -u VIRTUAL_USER -s LIST
- =back
- =back
- =head2 Slash 2.2.6 -E<gt> Slash CVS
- Use the sql/mysql/upgrades file; see L<"VERSIONS">, "CVS tags", below.
- This file is human-readable and very long. You can upgrade a 2.2.6 to
- the latest CVS by methodically applying every step in this file, but
- it is tedious and requires an engaged human brain reading the comments
- (i.e., don't "mysql slash < upgrades", that will fail miserably).
- =head2 Slash CVS -E<gt> later Slash CVS
- Again, use the sql/mysql/upgrades file (and the caveat just mentioned
- still applies). Start from the CVS tag you left off at, and proceed
- to the CVS tag you upgraded to (which should be the end of the file).
- If you're not sure which tag you left off at, you might check the var
- 'cvs_tag_currentcode', which will contain the right value if you last
- updated after September 2005.
- In general, you should stop apache and slashd, do a "make install",
- apply the upgrades file a line at a time for each Slash site, run
- "template-tool -U -u virtusename" and "symlink-tool -U -u virtusername"
- for each Slash site, and then start slashd and apache back up.
- =head1 REQUIREMENTS
- =head2 Software Requirements
- Below, we list the main software components needed. The recommended
- version is given. Usually this is the version we have done extensive
- testing on, typically a version we have used on Slashdot for some time.
- In parentheses we include (but do not recommend or support) the earliest
- version we believe could work.
- =over 4
- =item Perl
- Version 5.8.7 (5.6.1).
- http://www.cpan.org/
- =item MySQL
- Version 5.0.22 (4.0.12).
- http://www.mysql.com/
- MySQL 3.23.x is no longer supported, as of CVS tag T_2_5_0_33
- (October 18, 2004). MySQL 4.0.x is not being actively updated by
- MySQL AB except for security issues (though as far as we know it still
- works fine), so we would recommend that you upgrade to at least 4.1.x.
- At some point in the future we will switch over to some syntaxes which
- have been recommended for some time which will break on 4.0.x, so you'll
- have to upgrade to at least 4.1.x eventually anyway. (You probably have
- until 2007 before we spring this on you.)
- Slashdot ran on 4.1.x for a long time with no problems, so we now
- recommend either that or 5.0.x. We have been testing on 5.0.x for months,
- and as of this writing (August 2006), Slashdot has been running on 5.0.18
- and 5.0.22 for some time with no problems. For what it's worth, we have
- found the MySQL upgrade process, even between major versions, to be about
- as painless as we could have imagined.
- =item Apache
- Version 1.3.34 (1.3.33).
- http://httpd.apache.org/
- Since most of Apache 1.3.x's recent releases included security fixes,
- we wouldn't recommend running an earlier version. Slash is not compatible
- with Apache 2.x and we have no plans to port to 2.x (though we aren't
- excluding the possibility).
- =item mod_perl
- Version 1.29.
- http://perl.apache.org/
- =item memcached
- Version 1.1.12 (1.1.11).
- See "Memcached" above.
- =item Sendmail or other mail transport agent
- Refer to your OS distribution.
- =item Perl module distributions
- The latest version of each perl module is recommended. To download and
- install them, use CPAN -- see L<"INSTALLATION">, item 4, "Install the
- perl modules."
- =item Libraries
- For Compress::Zlib, the zlib development library is required. For
- XML::Parser, the expat library is required. If they are not present
- on the system already, download and install them before installing
- the modules.
- http://www.gzip.org/zlib/
- http://sf.net/projects/expat/
- The current list of required perl modules can be found in the
- F<Bundle/Slash.pm> file. At its end we also list optional modules,
- which may be required depending on your setup.
- =item Debian libraries
- On Debian Linux, or Debian-based distributions like Ubuntu, the above
- libraries can be installed with:
- apt-get install zlib1g zlib1g-dev libexpat1 libexpat1-dev
- Also on Debian, as of the current writing (July 2006), you will want
- libperl-dev. DBD::mysql requires mysql_config and mysql.h; on Debian
- stable, try libmysqlclient12 (and -dev) for 4.0.x and/or libmysqlclient14
- (and -dev) for 4.1.x. On testing or unstable, try libmysqlclient15off
- and libmysqlclient15-dev.
- =back
- =head2 Hardware Requirements
- There are no specific hardware requirements.
- Slash is designed to work well on multi-machine setups, with one or
- more webheads that are separate from one or more MySQL DB machines.
- But for low-load sites (1-5 pages/sec or slower), it can probably be
- run OK on a single machine.
- Apache (with mod_perl) and MySQL both take up a lot of RAM. Running a
- complete system with 128MB might be possible, if you do some tuning of
- the configuration, but a practical minimum of 256MB is recommended, and
- you will be much happier with at least 1GB of RAM. See L<"INSTALLATION
- OPTIONS">, "Separate Image Server" for tips on saving some RAM.
- Disk space depends on how busy you expect the site to be. Slash keeps
- a small database -- even Slashdot's DB compresses down to a few GB.
- The disk files as installed are under 0.5 GB, and grow predictably as
- stories and comments are added (keep an eye on the F<site/foo/logs/>
- directory, too). A minimum of 1 GB of disk is recommended.
- Necessary processor speed is also dependent on how busy the site is.
- A Pentium II/400 equivalent is recommended, but obviously, the faster
- the better.
- For the curious, Slashdot (as of September 2001) runs on nine machines:
- nine webservers (each is Pentium III/600, 1GB RAM, 9GB hard drive), one
- NFS server (600MHz PIII, 1GB RAM), and three database servers
- (quad 600MHz PIII, 4GB RAM). One database server is
- live, one is a replicated backup, and a third is for doing live searches
- and performance-intensive SELECTs by daemons etc.
- However, this is certainly overkill for most sites (and possibly even
- overkill for Slashdot). slashcode.com runs on two web servers and one
- NFS/database server. Many sites can run fine on just one machine for
- everything (we use a minimum of two web server machines on every site
- for load balancing and redundancy).
- If you're concerned about performance, the F<bin/mechmonkey> script
- may help provide load vaguely similar to real user patterns, though
- it doesn't try simulating logged-in users. One more data point: my
- personal machine is a 2.4 GHz Athlon with 1.5 GB RAM and an IDE disk,
- and it easily handled the load when its Slash site got a mild Slashdotting
- (a link in a non-major story, about 10 pages/sec).
- =head1 VERSIONS
- Each version of slash has a code name, and the files on CVS for that
- version are tagged with that name. The current release is always
- MAIN. The versioning scheme is as Linux and perl are,
- revision.version.subversion. version is even for releases, and odd
- for development. The codename applies to the development version
- and subsequent release.
- For example, 1.0.11 is a normal release, while 1.1.0 is the first
- development release for what will be the next release (either 1.2
- or 2.0).
- The CVS repository is tagged with version numbers, so to get release
- 1.0.3, use tag "v1_0_3_0". The last number (in this case a zero) will
- be incremented during development ("v1_0_3_1", "v1_0_3_2", etc.) until
- the next release. Non-release versions are tagged with a T_ or R_
- prefix. We are currently developing 2.5.x, so our CVS tags are
- T_2_5_0_x and R_2_5_0_x (though there was no 2.4.0 release and to date
- has been no 2.5.0).
- =head2 Codenames
- =over 4
- =item v1.0
- beast
- =item v2.0
- bender
- =item v2.2
- fry
- =item v2.3
- (never released)
- =item v2.4
- (never released)
- =item v2.5
- leela
- =back
- =head2 Security note
- We are no longer releasing bugfixes, even for security, for the 1.0
- or 2.0 versions, and do not recommend their use. If we become aware
- of security issues in the 2.2 tree, we will release another version.
- For this reason, if you are using any version of Slash in 2.2.x or
- earlier, we recommend you upgrade at the very least to the latest version
- of 2.2, which as of this writing (August 2006) is 2.2.6.
- =head2 CVS tags
- Our development of 2.3/2.5 has gone on exceptionally long without a
- tarball release of either 2.3.0 or 2.5.0. Most Slash hosting sites are
- choosing to follow CVS instead of waiting, and we encourage this.
- Installation of the latest CVS (as of August 2006) is almost identical
- to the installation of 2.2.
- You probably do not want to use the
- very latest CVS, as the Slash developers are constantly updating it.
- If you wish to live on the edge, try a T_2_5_0_x tag ("Testing in 2.5.0
- branch" -- one or two of these are added every week, Slashdot uses them,
- but they may have bugs). If you are content with recent code that the
- developers believe is likely to be free of major bugs, look for a recent
- R_2_5_0_x cvs tag ("Release candidates for 2.5.0").
- To upgrade from 2.2.x to the CVS tree, you will need to follow the
- instructions in the sql/mysql/upgrades file. At the moment, these are
- just SQL commands you will need to issue, but read carefully because
- you may have to use judgement and issue command-line commands and so on.
- (We are working on a tool to automate this process.) Once you are
- upgraded to, or have installed, a given CVS tag, upgrading to later
- CVS tags is simply a matter of following along in that file -- we append
- as we go, and each T_* tag is clearly marked.
- =head1 TROUBLESHOOTING COMMON INSTALLATION PROBLEMS
- Here are some common errors reported by other site administrators.
- =over 4
- =item *
- Webpages show the error: "The server encountered an internal error or
- misconfiguration..."
- Check your Apache error logs for a more specific error.
- =item *
- "Can't locate Slash.pm in @INC..."
- One possibility is that you didn't actually C<make install> Slash
- in step 5, which would be a pretty serious omission.
- It's also possible that the apache or slashd process issuing this error
- doesn't have permissions to read Slash.pm, or is using a different version
- of perl than you expect with a different set of @INC directories than
- you expect. Try, at the command line:
- which perl
- head -1 /usr/local/slash/sbin/slashd
- perl -MSlash -le 'print $INC{"Slash.pm"}'
- and see if it emits the perl binaries you expect and the location of
- Slash.pm that you expect. Check file permissions and see "Multiple perls
- installed" below.
- =item *
- I installed Slash twice and it didn't work.
- Did you uninstall before reinstalling? See "UNINSTALLING" below.
- If you intend to reinstall with the same database and site name,
- steps 4 and 7 are not optional.
- =item *
- "Can't locate MIME/Types.pm in @INC..."
- This used to be required only for plugins/Blob and you probably didn't
- follow its README after you installed it. Now it's in Bundle::Slash; try
- reinstalling Bundle::Slash (and see "Old Version of Bundle::Slash" above).
- =item *
- DBD::mysql will not install.
- As of October 2006, its tests by default assume you have a running mysqld
- on localhost, with a database named 'test', accessible to the user
- 'root' with no password. If you don't have a database named 'test',
- create one with C<CREATE DATABASE test;>. If you don't run mysqld
- on the same machine as you're installing the module, or if you have a
- password for its 'root' user (good idea), almost all its tests will fail.
- You can either override the failures with
- cpan> force install DBD::mysql
- or (better) run proper tests by telling it the actual mysqld host, user,
- and password to connect to, with
- cpan> look DBD::mysql
- # perl Makefile.PL --usage
- # perl Makefile.PL --testmycustomargs=foobar
- # make && make test && make install
- =item *
- "Can't call method '(whatever)' on an undefined value at..."
- Slash can't connect to your database server. (This manifests as the
- variable $slashdb being undef. Which method happens to emit this error
- depends on which code path first tries to use $slashdb.)
- To start troubleshooting this, see "Database authentication issues" below.
- =item *
- I created a new author but s/he doesn't show up in authors.pl and can't
- post stories.
- For performance reasons, Slash aggressively caches the list of which
- users are authors. After you mark a user as an author and boost their
- seclev (maybe to 100) in users.pl, go back to the command line and run
- the refresh_authors.pl task by hand:
- # /usr/local/slash/bin/runtask -u yourvirtuser refresh_authors
- Then restart apache and slashd. That user will now be able to post
- stories. The authors.pl listing will update some time after the first
- story is actually posted.
- =item *
- Freshly-posted stories aren't showing up on the homepage.
- Are you sure slashd is running? If a story appears on /index.pl but not
- /index.shtml, and it's more than a few minutes old, check the output of
- 'ps' for slashd, and check slashd.log for errors.
- =item *
- "Use of uninitialized value in..."
- Just a harmless warning, ignore it. It helps us find errors, but you
- don't need to worry about it.
- =back
- Here are some other common reasons why Slash installations fail.
- =over 4
- =item *
- Failure to build mod_perl with PERL_MARK_WHERE=1 EVERYTHING=1.
- We emphasize this in the instructions for a reason. Go back and
- reread the Installation Procedure, step 3.
- =item *
- Perl module installation troubles.
- If you have a unix-like system with CPAN properly installed
- and no serious firewall issues, perl module installation will
- usually go pretty smoothly…
Large files files are truncated, but you can click here to view the full file