Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
tree: 23f6ce8ab5
Fetching contributors…

Octocat-spinner-32-eaf2f5

Cannot retrieve contributors at this time

file 613 lines (460 sloc) 26.294 kb
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612
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/project/?group_id=4421

        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.

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

    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.

                http://whateveryoursiteiscalled.com/admin.pl

        The admin user/password is God/pete (you'll need to change this).

        This page allows you to 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/

AUTHOR
    Patrick Galbraith and Chris Nandor. Last Modified July 10, 2000.

Something went wrong with that request. Please try again.