ISFDB:Personal Windows Website

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.


 * {|class="TablePager"

! Application !! Main Download Area !! Recent Version !! Kit
 * rowspan="2"|Apache
 * rowspan="2"|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
 * }
 * 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:
 * 3) * Network Domain can be anything (blank is not allowed)
 * 4) * Server Name should be "localhost"
 * 5) * Administrator Email can be anything (it is displayed in error pages)
 * 6) * Choose for All users, on Port 80, run as a service
 * 7) * Perform a Typical installation
 * 8) * 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
 Download the Windows binary (MSI installer) listed in Current Kits above. 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 (or type "mysql" in a Command Prompt or Cygwin window) 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.
 * 3) * Install for all users
 * 4) * You can take all of the defaults or make changes as you deem appropriate.
 * 5) * 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 (from a Command Prompt or Cygwin window) 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.)
 * 3) * The Python installation just done above should be listed and selected.
 * 4) * 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.
 * 3) * Take the defaults, changing locations to suit your environment
 * 4) * Pick a mirror near you
 * 5) * In the Packages list, expand Devel and
 * 6) ** Select "make" (not installed by default)
 * 7) ** If you want to run command-line CVS, you can also select "cvs".
 * 8) * In the Packages list, expand Utils and
 * 9) ** Select "diffutils" (not required; for using diff with CVS)
 * 10) * Complete the installation. A desktop icon is not needed unless you want easy access to a shell environment.
 * 11) Add the Cygwin bin directory (e.g., C:\cygwin\bin) to your system Path. (You may need to restart your machine for the System Path changes to take effect.)

Typing make -v in a Command Prompt or Cygwin window 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.
 * 3) * Take the defaults
 * 4) * Do a full installation
 * 5) * Allow the installation to restart Windows Explorer

Download the ISFDB Source
The ISFDB source is stored at SourceForge and is accessed via CVS. Anonymous CVS 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. [Late 2012 note: SourceForge has been having problems with anonymous access to their CVS repositories since late November 2012, so its availability varies.]

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:



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 from a Command Prompt or Cygwin window:

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:



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 commands from a Command Prompt:

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

or from a Cygwin window:

export CVS_RSH=ssh export 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
  Edit isfdb2\common\localdefs.py: HTMLLOC        = "127.0.0.1" HTFAKE         = "cgi-bin" (if using IIS, this should be "cgi") DBASEHOST      = "localhost" WIKILOC        = "www.isfdb.org/wiki" HTMLHOST       = "127.0.0.1" COOKIEHOST     = "127.0.0.1" LOCALFILES     = "directory where files generated by the night job reside" 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

  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

</li>  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. </li>  Then in a Command Prompt or Cygwin window, 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. </li>  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. </li> </ol>

Configure Nightly Processing
Configure Cygwin's crontab to run nightly_update.py in the "nightly" subdirectory under INSTALL_HTML. This file will rotate the ISFDB banner at the top of each ISFDB page and will regenerate certain database statistics information.

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, in a Command Prompt or Cygwin window, execute:

python isfdb2\scripts\create_user.py LoginName password

replacing LoginName and password above with the actual login name and password you want to use on your local install. 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.