Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Fetching contributors…

Cannot retrieve contributors at this time

662 lines (508 sloc) 27.571 kb
NAME
INSTALL - Slash Installation
SOFTWARE REQUIREMENTS
Whatever versions listed are the versions recommended. You may
try a newer version, and it should work, but it is not
guaranteed (of course, nothing in here is guaranteed anyway :).
Don't try to use anything older than these listed versions.
This document is still evolving, so there may be unintended
omissions or various steps may be over- or under-explained. It's
assumed that you have some working experience with some form of
Unix, Apache, SQL database, and perl.
Note: This page looks best in a browser (the HTML version of it
is in the docs/ directory). You can print it out, but some of
the ASCII illustrations may get munged in printing; however, the
directions will certainly appear good enough to read.
See the Slash web site, with support, docs, latest downloads,
and more, at http://slashcode.com/.
Database, webserver, etc.
MySQL
version 3.22.25
http://www.mysql.com/
mod_perl
version 1.21
http://perl.apache.org/
http://www.perl.com/CPAN/
perl
version 5.005_03 (non-threaded)
http://www.perl.com/CPAN/
Apache
version 1.3.6
http://apache.org/
Sendmail or other mail transport daemon
Refer to your OS distribution.
NFS server (for nfs configuration)
Refer to your OS distribution.
Perl modules
DBI-1.14
http://search.cpan.org/search?dist=DBI
Data-ShowTable-3.3
http://search.cpan.org/search?dist=Data-ShowTable
TimeDate-1.08
http://search.cpan.org/search?dist=TimeDate
Msql-Mysql-modules-1.2209
http://search.cpan.org/search?dist=Msql-Mysql-modules
ApacheDBI-0.87
http://search.cpan.org/search?dist=ApacheDBI
Apache-DBILogConfig-0.01
http://search.cpan.org/search?dist=Apache-DBILogConfig
Apache-DBILogger-0.93
http://search.cpan.org/search?dist=Apache-DBILogger
libnet-1.0607
http://search.cpan.org/search?dist=libnet
HTML-Parser-2.25
http://search.cpan.org/search?dist=HTML-Parser
XML-Parser-2.27
http://search.cpan.org/search?dist=XML-Parser
MIME-Base64-2.11
http://search.cpan.org/search?dist=MIME-Base64
Digest-MD5-2.09
http://search.cpan.org/search?dist=Digest-MD5
URI-1.04
http://search.cpan.org/search?dist=URI
libwww-perl-5.47
http://search.cpan.org/search?dist=libwww-perl
DateManip-5.35
http://search.cpan.org/search?dist=DateManip
File-Spec-0.8
http://search.cpan.org/search?dist=File-Spec-0.8
Mail-Sendmail-0.77
http://search.cpan.org/search?dist=Mail-Sendmail
Compress-Zlib-1.08
http://search.cpan.org/search?dist=Compress-Zlib
Image-Size-2.901
http://search.cpan.org/search?dist=Image-Size
Storable-0.6.9
http://search.cpan.org/search?dist=Storable
Note: IPC::Shareable is only needed for the troll speed
limit feature, which is off by default (settable via the
`use_ipc' variable in slashdotrc.pl). Also, on all of our
test systems, some of the tests in `make test' failed, but
the module seems to work fine for our purposes regardless.
Slash Code
Bundle/Slash.pm
Slash.pm
slashd
moderatord
portald
dailyStuff
public_html/index.pl
public_html/comments.pl
public_html/article.pl
public_html/admin.pl
public_html/hof.pl
public_html/cheesyportal.pl
public_html/authors.pl
public_html/metamod.pl
public_html/nominate.pl
public_html/pollBooth.pl
public_html/search.pl
public_html/sections.pl
public_html/submit.pl
public_html/topics.pl
public_html/users.pl
public_html/404.pl
public_html/imagesize.pm
You can get the Slash code in these locations:
FTP ftp://ftp.slashdot.org//pub/slash/
HTTP, CVS
http://sourceforge.net/projects/slashcode/
The CVS repository is tagged with versions, so to get
release 1.0.3, get tag "v1_0_3_0". The last number will be
incremented during development ("v1_0_3_1", "v1_0_3_2",
etc.) until the next release. Sometimes, a release may be
tagged with a last number of something other than "0".
Exactly what tag a given release is based on is in README.
There is a separate development branch of Slash. Its branch
is "bender". Primarily small changes and bugfixes will go
into the MAIN branch, with major changes going into the
development branch.
Hardware Requirements
None. Whatever it takes to run the above software and handle
the traffic you may be getting. You could probably do it on
a 486 with 32MB and 250MB hard drive space, but we wouldn't
recommend it. Minimum setup would probably be some sort of
Pentium 133 or higher, 128MB, and 1GB HD. I'd shoot for at
least a Pentium II/200+ MHz, 256MB, 2GB. Consider also that
the httpd machine might be different from the mysql machine,
you can keep the number of httpds real low, etc. Do what
works.
PRE-INSTALLATION THOUGHTS
The are several configurations recommended, depending on scale.
Single server (all on one box)
Server 1
+-------------------+
| slash db |
| apache/mod-perl |
| slash code |
+-------------------+
db and code on one server, and external webserver
server 1 server 2 .. n
+-----------------+ +-----------+
| slash db | | |
| apache/mod-perl |---- NFS or exact copy ----| Webserver |
| slash code |---- NFS or exact copy ----| |
+-----------------+ +-----------+
|_________________ DBI __________________|
db separate on one server, slashdot code and apache on another,
exported to web servers
server 1 server2 server 3 .. n
+-----------+ +-----------------+ +-----------+
| slash db | | | | |
| | | apache/mod-perl |--- NFS or exact copy ---| Webserver |
| | | slash code |--- NFS or exact copy ---| |
+-----------+ +-----------------+ +-----------+
|______ DBI _________|_______________________________________|
There are many ways this can be done. The key is to think about
how the site will be put together before starting the
installation.
Note: If your site is going to be very busy, you may wish to
consider having a separate images server. For instance, Slashdot
has images.slashdot.org, which handles all the images. Just set
the imagedir variable in slashdotrc.pl appropriately, like
`http://images.example.com'.
INSTALLATION AND SETUP
Perform these tasks as root.
1. Create the group "slash".
2. Create the user "slash" with slashdot gid. Note: if using
multiple webservers, and using NFS, make sure that this
user:group is created with the same UID and GID on all
involved systems.
Note: For security's sake, you may wish to add the web
server user (e.g., "nobody") to the "slash" group, and then
set your permissions so that all the files are writable by
user and group and not world, to keep other users on the
system from modifying the files.
3. Unpack the slash code tarball in the slash user's home
directory. This will place everything where it should
belong.
4. chown everything in this tree as slash:slash (i.e., `chown -R
slash:slash /home/slash'). chmod the main directory to be
readable and executable by all (i.e., `chmod a+rx
/home/slash').
5. Create the directory apache will be installed into (i.e.,
/usr/local/apache). The default install uses a separate
directory for apache logs, which should also be created as
/usr/local/apache_logs. Alternatively, change httpd.conf to
point to a different location. See the section below on
installing perl modules for more information about the
default installation.
Multiple slash instances can run under virtual hosts on the
same httpd. See vhost.httpd.conf for an example of how this
works. Pay special attention to the configuration section
under the text "# MAIN SLASHCODE SPECIFIC STUFF STARTS HERE
#".
For virtual hosts, you should create a separate account and
Slash installation for each virtual host, so repeat the
instructions relating to creation of accounts for each
virtual host.
6. Install MySQL. Please refer to MySQL documentation for
compilation and/or installation notes for any questions with
this. Find the script that runs mysql (probably safe_mysqld)
and add this to the beginning of it:
TZ=GMT
export TZ
Note: For slashd (see utils/slashd, which starts slashd),
mod_perl (see httpd/httpd.conf), and MySQL, we set all
processes to run in GMT. Then it is easy to convert dates to
whatever the user's local time is. If you have date
problems, check that all of these are properly set to run in
GMT.
7. Create the slash mysql user and database.
mysql mysql < sql/slashdb_create.sql
This will create both the slash db user and slash db. If you
are using virtual hosts, or want to otherwise change the db
user or db name, edit this script before running it to use
the proper db user and db name. This script creates the user
slash with the password "changethis". Immediately change the
password for slash in mysql:
mysql mysql
update user set Password = password('newpassword') where User = 'slash';
flush privileges;
Note: The slash db user is created with several privileges
such as drop and create table, so it's up to you to modify
those privileges to something more restrictive if you feel
uncomfortable with these settings. We'd suggest you don't
let other users on the database have access to this user.
8. Run the slash schema creation script and load sample slash db
data dump. This dump has minimal data for the system to
work. This data is needed in the database for the site to
work at all. It has a very plain, basic design, that has a
lot of HTML comments in each block to give an idea of how
the site works. Other data in this dump is tables that the
system needs to do things such as time conversion for user
date format strings. Please refer to the database schema and
database schema documentation to understand how the database
schema works.
Replace `HOSTNAME' (or `HOSTNAME:PORT') below with the
server's hostname (this is the name you will call the server
in the browser, used for default links in the HTML).
cd sql
mysql -uslash -pnewpassword slash < slashschema_create.sql
./predata_dump.pl HOSTNAME
mysql -uslash -pnewpassword slash < slashdata_dump.sql
mysql -uslash -pnewpassword slash < slashdata_prep.sql
9. Install perl.
On Slashdot and Slashcode, we have all of the modules
installed in the Apache directory, so that we can NFS mount
that one directory on several machines, and they all have
the same modules and configuration. If you want to do that,
when the configuration process asks where you want to put
perl modules (both system and local) have it put them in the
directory tree you'll install apache in (i.e.,
/usr/local/apache/lib). Otherwise, the default installation
directories are usually fine.
10. Untar apache and mod_perl. Build mod_perl. Have its build
process build and install apache for you:
perl Makefile.PL APACHE_SRC=/where_you_have_the_source DO_HTTPD=1 \
USE_APACI=1 PERL_MARK_WHERE=1 EVERYTHING=1 \
APACHE_PREFIX=/where_apache_will_be_installed
make
make test
make install
This will install both mod_perl and apache.
You MUST install mod_perl and Apache as directed here. OK,
that is not strictly true, but it is mostly true. If you
already have mod_perl installed, chances are it is not
configured properly to work with Slash and you must rebuild
it. If you are using the provided httpd.conf file from the
slash distribution, and Apache is giving you errors, chances
are mod_perl is not installed correctly, and you need to
build it from scratch.
11. Install the listed perl modules in the order listed in the
section on "Perl Modules". You can use CPAN if you want, or
ftp, untar and do it yourself. Use whichever does the job.
Note that the module versions Slash has been tested with are
given; use other versions at your own risk. We actually
think that the current version of each module as of this
note will work, so if you are brave, go ahead and install
the latest.
You can get the files via FTP yourself from CPAN and then
install each by hand, or, if you can get the CPAN module
running, you can use that. There are several ways to use the
CPAN shell to install modules. You can install each one
individually:
perl -MCPAN -e shell
# some configuration / initialization stuff
> install DBI
Or, you can install all of them at once using the
Bundle::Slash module. This method is the easiest, but if
something does not work right, it can be more of a pain to
track it down.
cd /home/slash
perl -MCPAN -e "install 'Bundle::Slash'"
You may also want to use CPAN shell to install
Bundle::libnet, Bundle::LWP, Bundle::DBI,
Bundle::DBD::mysql, and then the rest of the modules. See
the manpage the perlmodinstall manpage for more information
about using CPAN and installing modules.
Note: Compress::Zlib is now required, and it won't install
properly if the zlib development headers are not available.
See the documentation for Compress::Zlib for more
information.
Note: File::Spec is now required, but a version beyond what
comes with perl 5.00503 is required. Use `make install
UNINST=1` to remove the version that comes with perl while
installing the new version. Even if using the CPAN shell you
can do this:
cpan> test File::Spec # download, make, and test
cpan> look File::Spec # opens shell to proper dir
% make install UNINST=1 # install from shell
12. Copy the slash httpd.conf from the untarred slash code tarball's
directory httpd (i.e., /home/slash/httpd/httpd.conf) to
apache's conf directory. Take time to look over the file to
make sure that it matches your site's specific setup.
Similarly edit /home/slash/slashdotrc.pl.
For httpd.conf, pay close attention to directories and to
the number of servers and the max clients and requests. The
defaults are similar to Slashdot's defaults, but most sites
will not need 20 servers with over 100 maximum requests per
child process.
In slashdotrc.pl, make sure you have reasonable defaults for
everything. If you are upgrading, then you will likely want
to make a copy of your old slashdotrc.pl and copy those
values into the new file, since it is subject to change
significantly from one release to the next.
If your web server is inside a firewall, you may wish to set
the rootdir variable to "" (it is below the other variables,
toward the bottom), so all links will be relative to /.
If you are doing virtual hosting for multple Slash sites,
see the instructions at the bottom of slashdotrc.pl and the
sample configuration at the bottom of httpd.conf.
13. Create /etc/apache.listen (where `MY.IP.ADD.RESS' is the IP
address Apache will be listening on):
echo "Listen MY.IP.ADD.RESS:80" > /etc/apache.listen
14. Start apache.
15. Copy the slashd startup script from the Slash source directory
(i.e. /home/slash/utils) slashd into the init.d directory
(/etc/init.d on Debian). Chown it to the slash user (i.e.,
`chown slash:slash /etc/init.d/slashd') and then chmod it
u+s and g+s (i.e., `chmod u+s /etc/init.d/slashd', `chmod
g+s /etc/init.d/slashd') Create all the links to this file
for the various run levels. Note: this script is a startup
script, and is not the same script as the slashd in the same
directory as Slash.pm.
16. Start slashd with the startup script (i.e., `/etc/init.d/slashd
start').
17. Log into the server administration.
Run the script `sql/adminuser_create.pl'. This will create
the default admin user account that you will use to log in.
This script will ask you the name you want to use as your
site's admin user, and then ask you a password to use for
this user. Use a good password, you don't want it to be
something guessable.
http://whateveryoursiteiscalled.com/admin.pl
This page allows you to edit your admin user accounts
settings, create new admin users, approve submissions to be
run as stories, add new stories, edit stories, edit the
blocks of html, code, and variables that control the look
and feel of the site.
The system has 7 users:
author1
author2
Anonymous Coward
user1
user2
user3
user4
The passwords are all "change". As that implies, you should
change it. It's clear text, so simply change it via the
database, although you can use the server administration,
too. If you do not change all your passwords, you almost
certainly will get haX0rD.
mysql -uslash -pslashpass slash
Then for each author:
update authors set pwd='newpassword' where aid='authorname';
And for each user:
update users set passwd='newpassword' where nickname='username';
You can see all of the authors and users with these:
select aid,pwd from authors;
select nickname,passwd from users;
Running Slash on Multiple Servers
1. Make sure that each of those servers has an EXACT copy of the
entire apache tree (modules and all).
2. Either remote copy recursively, or simply export the entire
apache tree via NFS (read-only) to the servers you intend to
be the web servers.
3. Make sure that whatever box is running slashd has all of its
code and static documents exported to those web servers as
well (read-only).
4. Make sure that the slash user in mysql can access the database
from any host that has the code on it:
mysql mysql
insert into user values
('webserver1','slash',password('newpassword'),'Y','Y','Y','Y','Y','N','N','N','Y','Y','Y','Y','Y','Y');
insert into user values
('webserver2','slash',password('newpassword'),'Y','Y','Y','Y','Y','N','N','N','Y','Y','Y','Y','Y','Y');
insert into user values
('webserver3','slash',password('newpassword'),'Y','Y','Y','Y','Y','N','N','N','Y','Y','Y','Y','Y','Y');
insert into user values
('webserverN','slash',password('newpassword'),'Y','Y','Y','Y','Y','N','N','N','Y','Y','Y','Y','Y','Y');
flush privileges;
Database Upgrades From Previous Versions
Slash is data. When we release a new version, it often has
updates to the database, too. As such, updates can be difficult.
We have provided upgrade scripts from previous versions of
slash. Each script upgrades from the version immediately
preceding it, so 0.9.2 users, to upgrade to 0.9.5, would need to
run the 0.9.3 scripts, then the 0.9.4 scripts, then the 0.9.5
scripts.
The scripts are stored in sql/updates/x.x.x/, where x.x.x is the
version to upgrade to. The .sql scripts can be run like so:
mysql -uslash -pslashpass slash < updatescript.sql
The Perl scripts should be run, however, from the main slash
directory, so all of the libraries can be found:
cd /home/slash
./sql/updates/0.9.5/updatescript.pl
You may also at some point choose to reinitialize the database
from scratch. For that, you can do something like this:
mysql mysql
mysql> drop database slash;
mysql> create database slash;
mysql> quit
cd sql
mysql -uslash -pslashpass slash < slashschema_create.sql
mysql -uslash -pslashpass slash < slashdata_dump.sql
mysql -uslash -pslashpass slash < slashdata_prep.sql
Upgrade 0.9.2 -> 0.9.3
If you have already installed slash-0.9.2, you may use the
alter_database.sql script to update the database, then run
blocks_update.pl (make sure you change the connect string) if
you don't want to start your database over from scratch.
However, the blocks table contains a lot of updated data in
slash-0.9.3 that must be fixed in order for slash-0.9.3 to work
at all: global variables in the blocks (like $rootdir and
$fg[2]) must be changed to the new style ($I{rootdir} and
$I{fg}[2]}). You can do this by hand, or use the dumped data in
slashblocks_dump.sql.
Upgrade 0.9.3 -> 0.9.4
The tables blocks and sectionblocks needed to be fixed to make
it so that they had a 1:1 correlation on every record for the
admin interface to be able to work correctly. There was a bad
mismatch between the two tables. We've added processes to help
upgrade for those that have put a lot of work into customizing
their sites and don't want to lose any of their work. First,
back up the blocks table by doing a dump, or simply back up
individual blocks by doing the following:
1. Check to see that your block has an entry in both blocks and
sectionblocks in the case the admin.pl didn't get it in
there properly:
select count(*) from blocks where bid = 'myownblock';
select count(*) from sectionblocks where bid = 'myownblock';
2. If there's only one of the bids in either record, you can insert
an entry by hand for that record as shown here.
If it is blocks that it's missing from, for a static block:
insert into blocks values ('myownblock','','',500,'',NULL);
For a portal block (something that's fetched via portald):
insert into blocks values ('myownblock','','',500,'portald',NULL);
If it is sectionblocks that it's missing from:
insert into sectionblocks values ('','myownblock',0,'',0,NULL,NULL,0);
If there are more than one record for a bid in
sectionblocks, delete one of them (probably the one without
a section).
3. If you want to back up a specific block, try something like:
select * from blocks where bid = 'myownblock' into outfile '/tmp/blocks.myownblock.txt';
select * from sectionblocks where bid = 'myownblock' into outfile '/tmp/blocks.myownblock.txt';
4. Run the sql script blocks_fix.sql. This script makes sure every
record has a match in each table, and also modifies the bid
column in sectionblocks to be the same as it is in blocks,
as well as some other fixes to some of the blocks:
mysql -uslash -pslashpass < blocks_fix.sql
Keep note of any errors you might see. On a new 0.9.3
distribution, untouched, unmodified data, this worked
without incident.
5. Run the sql script blocks_alter.sql. This script drops the
existing primary key on sectionblocks, which is a
combination of bid and section, and creates a new primary
key on bid (which prevents duplicates of the same bid).
mysql -uslash -pslashpass < blocks_alter.sql
If this gives you an error, it is most likely due to the
fact that there are duplicate bids in sectionblocks.
Identify those records and delete the extra one, then retry
this script. All block ids (bid) must be unique.
6. If you deleted any of the blocks that you backed up as show in
step 3, you can restore those blocks this way:
load data infile '/tmp/blocks.myownblock.txt' INTO TABLE blocks;
load data infile '/tmp/sectionblocks.myownblock.txt' INTO TABLE sectionblocks;
Upgrade 0.9.4 -> 0.9.5
Just run the scripts in the sql/updates/0.9.5/ directory. The
scripts blocks_backup.sql and fix_matchname.pl will update the
data and structure of the database, and everyone should run
them. The script blocks_update.sql should only be run by people
who want some of their blocks data changed. Examine the script
and CHANGES and determine if you want to run the script, or
whatever.
Other Upgrades
From To Run Scipts in Dir
------- ------- --------------------
0.9.5 -> 1.0.0 sql/updates/1.0.0/
1.0.0 -> 1.0.0.1 sql/updates/1.0.0.1/
1.0.0.1 -> 1.0.2 sql/updates/1.0.2/
1.0.2 -> 1.0.3 sql/updates/1.0.3/
1.0.3 -> 1.0.4 sql/updates/1.0.4/
1.0.4 -> 1.0.5 sql/updates/1.0.5/
1.0.5 -> 1.0.6 sql/updates/1.0.6/
1.0.{6-8} -> 1.0.9 sql/updates/1.0.9/
AUTHOR
Patrick Galbraith and Chris Nandor. Last Modified Monday,
October 2, 2000.
Jump to Line
Something went wrong with that request. Please try again.