ISFDB:Personal Windows Website

From ISFDB
Jump to navigation Jump to search

Follow these instruction to create a version of the ISFDB to run on your home Windows system. These instructions were developed on a Windows XP system and may need adjustment for Vista and later editions. If you are running 64-bit Windows, see the section on Windows x64 Considerations.

These instruction do not include setting up the ISFDB wiki.

Current Kits

This is a list of the recent versions of the kits referred to in these instructions. Binary installation packages are available for all external application used.

List last updated August 15, 2009.

Application Main Download Area Recent Version Kit
Apache http://httpd.apache.org/download.cgi 2.2.13 (no SSL) apache_2.2.13-win32-x86-no_ssl.msi
2.2.13 (SSL) apache_2.2.13-win32-x86-openssl-0.9.8k.msi
IIS On O/S media only 6.0 n/a
MySQL http://dev.mysql.com/downloads/ 5.1.x 5.1.html#win32
Python http://www.python.org/download/ 2.5.4 python-2.5.4.msi
MySQLdb http://sourceforge.net/project/showfiles.php?group_id=22307&package_id=15775 1.2.2-py2.5 MySQL-python-1.2.2.win32-py2.5.exe
TortoiseCVS1 http://sourceforge.net/project/showfiles.php?group_id=48103&package_id=41194 1.10.10 TortoiseCVS-1.10.10.exe
Cygwin1 http://www.cygwin.com 1.5.25 setup.exe

1The Cygwin Linux emulation environment for Windows has available a command-line CVS.

Set up the Web server

The ISFDB code relies on a web server. Two widely used choices on Windows are Microsoft IIS and the Apache HTTP Server. IIS is only available with Windows Server releases, so Apache is usually a more practical choice.

WARNING: The instructions here cover a basic installation of the web server and do not address properly securing a web server that is exposed to the Internet. If your web server is not behind a firewall or router set up to block inbound traffic, refer to the server's documentation and other sources for securing its configuration.

Setting up IIS

TBS

Setting up Apache

  1. Download the Windows binary (MSI installer) listed in Current Kits above. Use the most recent "stable" version. The ISFDB does not require SSL, so either package may be used.
  2. Run the downloaded file. The installation wizard will prompt for information used to set up an initial configuration:
    • Network Domain can be anything (blank is not allowed)
    • Server Name should be "localhost"
    • Administrator Email can be anything (it is displayed in error pages)
    • Choose for All users, on Port 80, run as a service
    • Perform a Typical installation
    • Use the default location or specify some other directory

At this point "http://localhost" in your browser should show you a page saying It Works!.

Set up the MySQL server

  1. Download the Windows binary (MSI installer) listed in Current Kits above.
  2. Follow the Windows instructions in ISDFB:MySQL Only Setup. This will load in the current version of the ISFDB data. The MySQL Only Setup does not contain all of the tables used by the web browser access. A symptom of missing tables is a SQL error that "mw_user_groups" does not exist. To get any missing tables, follow these steps additional steps:
    • Download http://www.isfdb.org/isfdb.sql.
    • Start up the mysql client and issue the following commands: 
         mysql> connect isfdb;
   mysql> source isfdb.sql;
      Errors about existing tables, etc. are normal and can be ignored.

NOTE: Windows Vista users will probably have to disable User Account Control (UAC) before installing MySQL.

Setting up an Empty Database

It is also possible to construct a blank version of the database, which can then be used to track the books in your library, or to create a different database altogether - like a database of Westerns, or Romance Novels. To follow this path:

  1. Download http://www.isfdb.org/isfdb.sql.
  2. Start up the mysql client and issue the following commands:
  mysql> drop database isfdb;
  mysql> create database isfdb;
  mysql> connect isfdb;
  mysql> source isfdb.sql;

Set up Python

MySQLdb (see Install MySQLdb below) is available for specific versions of Python, so you should check MySQLdb's Python version availability and download a matched set of Python and MySQLdb.

  1. Download the Windows binary (MSI installer) listed in Current Kits above.
  2. Run the downloaded file.
    • Install for all users
    • You can take all of the defaults or make changes as you deem appropriate.
    • After the installation completes, add the Python installation directory to the system Path. (You may need to restart your machine for the System Path changes to take effect.)

NOTE: Without changes, the ISFDB build environment will construct scripts expecting to find \usr\bin\python.exe on the same drive as the Apache process' working directory (by default, the same drive onto which Apache was installed). You can either install Python into \usr\bin instead of the default location, or you can install elsewhere and then mkdir \usr\bin and copy python.exe from the Python installation directory into it.

Install MySQLdb

MySQLdb is a python module that allows a python script to interface with the MySQL database. It uses the MySQL libraries, so MySQL must be installed prior to this step. It is installed into the Python modules area, so Python must be installed prior to this step.

  1. Download the Windows binary (EXE) listed in Current Kits above.
  2. Run the downloaded file. (If you get an "Unable to create Key" error message, you may need to right-click and choose Run as Administrator, even if the user you are logged in as has admin privileges.)
    • The Python installation just done above should be listed and selected.
    • Complete the installation

Python is now able to interact with the MySQL database.

Set up Unix Utilities

CVS and the build process use various Unix utilities (make, diff, etc.). There are several packages of ports of GNU utilities to Windows available. Cygwin is heavier-weight than some of the other options but provides the most complete environment and works well with the Unix-centric ISFDB build process.

  1. Download the setup.exe file listed in Current Kits above.
  2. Run this file.
    • Take the defaults, changing locations to suit your environment
    • Pick a mirror near you
    • In the Packages list, expand Devel and
      • Select "make" (not installed by default)
      • If you want to run command-line CVS, you can also select "cvs".
    • In the Packages list, expand Utils and
      • Select "diffutils" (not required; for using diff with CVS)
    • Complete the installation. A desktop icon is not needed unless you want easy access to a shell environment.
  3. Add the Cygwin bin directory (e.g., C:\cygwin\bin) to your system Path.

make -v should report "GNU Make 3.81" or a later version.

Set up CVS

In order to be able to retrieve the ISFDB source code from SourceForge, you must use CVS. Several CVS packages for Windows are available. A port of the Unix command line CVS is available for Cygwin (see above). For a more Windows-standard interface, TortoiseCVS provides a tight integration into Windows Explorer, without the need to work from the command line.

  1. Download the Windows binary (EXE) listed in Current Kits above.
  2. Run the downloaded file.
    • Take the defaults
    • Do a full installation
    • Allow the installation to restart Windows Explorer

Download the ISFDB Source

The ISFDB source is stored at SourceForge and is accessed via CVS. Anonymous CSV can be used to get a read-only copy. Developer access is required to modify the source and submit the changes.

Anonymous CVS Download From SourceForge

Anyone can get a copy of the ISFDB source via anonymous CVS access.

TortoiseCVS

Using TortoiseCVS, right-click on the folder in which you want the ISFDB root source folder to be created (e.g., C:\), and pick CVS Checkout... from the context menu. Copy and paste this line into the CVSROOT field of the Checkout dialog: 

  :pserver:anonymous@isfdb.cvs.sourceforge.net:/cvsroot/isfdb

or use the following configuration: 

  Protocol:          Password server (:pserver:)
  Server:            isfdb.cvs.sourceforge.net
  Repository folder: /cvsroot/isfdb
  User name:         anonymous

Leave the "Edit" option un-checked. The module is "isfdb2", but the "Fetch list..." button can be used to retrieve a list from the CVS server.

CVS Command Line

If you have a CVS command line tool installed, you can perform the download using the following command: 

  cvs -z3 -d:pserver:anonymous@isfdb.cvs.sourceforge.net:/cvsroot/isfdb co -P isfdb2

If you receive a "cannot rename file" error, change permissions on the newly created isfdb2 directory, e.g. "chmod 777 isfdb2", and rerun the cvs command.

Developer CVS Download From SourceForge

If you are an ISFDB developer, you can check out views, make changes, and check in updates. Requests to be an ISFDB developer must be approved by an ISFDB administrator at SourceForge. Developer checkouts also require that you obtain a login at SourceForge, generate an SSH key on your home system, and record your public key on the SourceForge site. Once those steps are complete, you can extract a developer view.

TortoiseCVS

Using TortoiseCVS, right-click on the folder in which you want the ISFDB root source folder to be created (e.g., C:\), and pick CVS Checkout... from the context menu. Paste this line into the CVSROOT field of the Checkout dialog, replacing login_name with your SourceForge login: 

  :ext:login_name@isfdb.cvs.sourceforge.net:/cvsroot/isfdb

or use the following configuration (again, replacing login_name with your SourceForge login): 

  Protocol:          Secure shell (:ext:)
  Server:            isfdb.cvs.sourceforge.net
  Repository folder: /cvsroot/isfdb
  User name:         login_name

Check the "Edit" option. The module is "isfdb2", but the "Fetch list..." button can be used to retrieve a list from the CVS server.

CVS Command Line

If you have a CVS command line tool installed, you can perform the download using the following command: 

  set CVS_RSH=ssh
  set CVSROOT=login_name@isfdb.cvs.sourceforge.net:/cvsroot/isfdb
  cvs -z3 -d:ext:login_name@isfdb.cvs.sourceforge.net:/cvsroot/isfdb co -P isfdb2

Install the ISFDB

  1. Edit isfdb2\common\localdefs.py: 
       HTMLLOC         = "127.0.0.1"
   HTFAKE          = "cgi-bin" (if using IIS, this should be "cgi")
   DBASEHOST       = "localhost"
   HTMLHOST        = "127.0.0.1"
   COOKIEHOST      = "127.0.0.1"
   USERNAME        = "root"
   PASSWORD        = "the password" (the password you set during the MySQL set-up)
   DBASE           = "isfdb"
   UNICODE         = "iso-8859-1"
   DO_ANALYTICS    = 0

    NOTE: Do not use "localhost" for HTMLLOC and HTMLHOST. Doing so causes IE7 (and possibly other browsers) to decide to ignore the cookies delivered by the ISFDB software when you log in. Using "localhost" will result in the login's succeeding but then your still being in a "not logged in" state.

    You will also need to access your ISFDB installation using the IP address for logging in to work. E.g., using: 

      http://127.0.0.1/cgi-bin/index.cgi
  2. Then edit isfdb2\INSTALLDIRS: 
       INSTALL_CGI     = path to Apache's cgi-bin (or IIS' cgi)
   INSTALL_HTML    = path to Apache's htdocs (or IIS' wwwroot)

    NOTE: Several utilities do not handle directory names with spaces, parentheses, etc. Also, backslash is a special character to some of the utilities, while all GNU utility ports can map Unix-style forward slashes to Windows-style backslashes. So use 8.3 names and forward slashes. E.g., 

       INSTALL_CGI     = c:/PROGRA~1/APACHE~1/Apache2.2/cgi-bin
   INSTALL_HTML    = c:/PROGRA~1/APACHE~1/Apache2.2/htdocs
  3. Check the directory permissions on your INSTALL_CGI and INSTALL_HTML directories. You'll either need to do the install as a user that has permission to write there, or you'll need to modify the permissions on the directories.
  4. Then execute: cd isfdb2 make -B install The "-B" is needed only the first time, or you will get an error about not knowing how to build ".TARGETS". Subsequent rebuilds do not need this.
  5. Place copies of isfdb2\INSTALLDIRS and isfdb2\common\localdefs.py someplace safe. If you do a cvs update on your source directory, and someone has checked in new versions of those files, you'll need to merge in your settings before installing again.

Enable ISFDB Editing

The ISFDB relies on MediaWiki to register users. In a personal setup without the Wiki, this is not possible. A script is provided to update the appropriate tables to allow editing permissions. After everything is installed and you are able to view pages in the isfdb, execute: 

  python isfdb2\scripts\create_user.py LoginName password

This will insert the login name and encrypted password into the correct tables.

Windows x64 Considerations

Some portions of the ISFDB environment can be set up using native Windows x64 variants instead of win32 (x86) files.

Mainstream x64 / EM64T/AMD64

  • Apache: No MSI installer available. x64-compiled binaries are available from http://www.blackdot.be/?inc=apache/binaries. Ok to use.
  • IIS: x64 status unknown.
  • MySQL: x64 MSI available at http://dev.mysql.com/downloads/mysql/5.1.html#winx64. Ok to use.
  • Python: x64 MSI available, BUT MySQLdb has no x64 version and will not work with x64-compiled Python. The win32 version must be installed anyway, so there's little to be gained by installing the x64 version.
  • MySQLdb: No x64 version available. Because it is win32, it requires a win32 version of Python be used. Trying to use it with the x64 Python will report that a suitable version of Python is not installed.
  • Cygwin: Works on x64 as-is.
  • TortoiseCVS: The kit is x64-aware and will install x64 native automatically (needed for context menues to work). Ok to use.

Itanium / IA64

If your machine is Itanium (IA64 vs. AMD64/EM64T), you're on your own. Software availability for this platform is very limited, and you are probably best off sticking with the 32-bit versions of all of the packages.

Retrieved from "https://isfdb.org/wiki/index.php?title=ISFDB:Personal_Windows_Website&oldid=236321"