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 a Windows system. 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 July 14, 2023.

Application Main Download Area Current Version Kit
Apache Archive of Wins32 Apache binaries 2.2.25 (no SSL)
2.2.25 (SSL)
MySQL MySQL Product Archives 5.5.62 (32-bit Windows) - last 5.5 version and the highest Windows version successfully tested so far; works under Windows 32 as well as Windows 64 mysql-5.5.62-win32.msi
Python http://www.python.org/download/ 2.7.18 for Windows32 python-2.7.18.msi
MySQLdb MySQL for Python download files 1.2.4b4 for Python 2.7 MySQL-python-1.2.4b4.win32-py2.7.exe
Cygwin https://cygwin.com 3.4.7 (2023) Setup version 2.925 32-bit version or 64-bit version

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. A personal version of the ISFDB system does not require SSL/HTTPS, 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://127.0.0.1" in your browser should show you a page saying It Works!.

Set up the MySQL server

NOTE: Windows Vista (and later) users may need to disable User Account Control (UAC) before installing MySQL.

Set up Python

  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 (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. (Note that the versions of Python and MySQLdb should match.)
  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

The ISFDB build process uses various Unix utilities (make, diff, etc.). There are several ports of GNU utilities to Windows available. For our purposes, Cygwin is the recommended package. Although it is heavier-weight than some other options, it 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)
    • In the Packages list, expand Utils and
      • Select "diffutils" (not required)
    • 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. (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.

Download the ISFDB Source

Use your browser to download the latest version of the ISFDB software from SourceForge. Unpack it in the directory tree of your choice. For the purposes of these instruction we will assume that you will call the top level directory "isfdb".

Install the ISFDB

  1. Edit isfdb\common\localdefs.py: 
       DBASE           = "isfdb"
   DBASEHOST       = "localhost"
   DO_ANALYTICS    = 0
   HTFAKE          = "cgi-bin" (if using IIS, this should be "cgi")
   HTMLHOST        = "127.0.0.1"
   HTMLHOST_ALT    = ""
   HTMLLOC         = "127.0.0.1"
   PASSWORD        = "the password" (the password you set up for MySQL)
   PROTOCOL        = "http"
   USERNAME        = "root"
   LEGACY_PASSWORDS= 1
   UNICODE         = "iso-8859-1"
   WIKILOC         = "www.isfdb.org/wiki (or 127.0.0.1/wiki if the ISFDB Wiki is installed locally)"

    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.

    • Note that HTMLHOST_ALT is normally set to an empty string for personal Web sites. You can set it to an alternative host name if using a real domain name as opposed to "127.0.0.1", e.g. "isfdb.org" if HTMLHOST is "www.isfdb.org".

    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 isfdb\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, in a Command Prompt or Cygwin window, execute: 
        cd isfdb
    make -B install

    The "-B" is needed the first time or when adding a new file name to one of the TARGETS file. Without the "-B" you will get an error about not knowing how to build ".TARGETS". Subsequent rebuilds which do not add new file names to TARGETS files can use "make install", which is much faster.

  5. Place copies of isfdb\INSTALLDIRS and isfdb\common\localdefs.py someplace safe. If you download a new version of the ISFDB software and someone has checked in new versions of those files, you'll need to restore your settings before rerunning "make install".

Configure Nightly Processing

See ISFDB:Configure Nightly Processing

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 isfdb\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

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=667397"