ISFDB:Personal Linux Website

Follow these instruction to create a version of the ISFDB to run on your home Linux system. These instruction do not include setting up the ISFDB wiki.

Setup the Web server

The ISFDB code relies on a web server. Apache is a good choice for this. The basic instructions are:

Installation

Many Linux distributions will include Apache as a package in their repository. This may be called 'apache', 'httpd' or some variant thereof. Alternatively you can download and install from the Apache Software Foundation:

1. Download the software. For Linux this is generally a source distribution, found at https://httpd.apache.org/download.cgi .
2. Follow the build instructions. In general, you should expect to uncompress, untar, run configure, run make, and run make install. The latter command will probably need to be run as a user account with root/sysadmin privileges.

Running the web server

Regardless of how you installed Apache, you will almost certainly need to configure it to start automatically after a boot. The exact method depends on how your Linux system manages the startup process. All of the following will need to be done by a user account with root/sysadmin privileges.

Linux system using init.d scripts

First copy the startup/kill script from the apache installation to the standard Linux location:

   cd /usr/local/apache2/bin
   cp apachectl /etc/init.d/httpd

Next setup the Start and Kill scripts from runstate 3 by creating symbolic links:

   cd /etc/rc3.d
   ln -s ../init.d/httpd S85httpd
   ln -s ../init.d/httpd K85httpd

Next setup the Start and Kill scripts from runstate 5 by creating symbolic links:

   cd /etc/rc5.d
   ln -s ../init.d/httpd S85httpd
   ln -s ../init.d/httpd K85httpd

Finally, if you want to startup Apache without a reboot:

   cd /etc/init.d
   sh httpd start

You should now be able to point a browser at your machine's IP address (or localhost) and see something.

Linux system using systemd

Many newer Linux distributions have switched to Systemd. To cause Apache to be started at boot time, do:

   systemctl enable httpd

(It is possible that the "httpd" service name may named be something else on your system, e.g. "apache".)

Note that the "enable" command only enables the Apache server, but does not start it running. To start Apache, type:

   systemctl start httpd

To stop a running Apache server, type:

   systemctl stop httpd

To disable Apache from starting at boot time, type:

   systemctl disable httpd

There are many other systemctl subcommands, which are documented on its "man" page.

Set up the MySQL server

For this step, follow the Linux instructions found in ISFDB:MySQL_Only_Setup#Linux_Installation. This will load the current version of the ISFDB data.

Install Python

Install Python 2.7.18. You can download it from python.org. Note that earlier (2.6, 2.5, etc) or later (3.0, 3.1, etc) versions of Python will not work with the ISFDB software. There is a plan to upgrade to Python 3, but it's hasn't been done yet.

Install MySQLdb

MySQLdb is a python module that allows a python script to interface with the MySQL database. The module includes C code, so it requires the standard Linux development tools. It uses the MySQL libraries, so MySQL must be installed prior to this step. Finally, it is installed in the Python modules area, so Python must be installed prior to this step.

1. Install the development tools. This contains the C compiler, which is needed to compile and link elements of the MySQLdb module. You can test if the development tools are present by typing cc. If cc is present it will output:

  $ cc
  cc: no input files

If the tools are not present you will see:

  $ cc
  -bash: cc: command not found

2. Install python-devel. This module is required in order to install additional Python packages, such as MySQLdb. Your version of Python may already have this module installed.

3. Install the MySQLdb Python module. This can be found at https://sourceforge.net/projects/mysql-python/. At this point Python will be able to interact with MySQL.

Alternatively, if you are running in a virtual environment (as described further down), then 'pip install mysqlclient' seems to provide an acceptable version of this library.

Download the ISFDB Source

Use your browser to download the latest version of the ISFDB software from SourceForge.

Install the ISFDB

1. Edit common/localdefs.py under the main source code directory. Enter the following values:

  DBASE           = "isfdb"
  DBASEHOST       = "localhost"
  DO_ANALYTICS    = 0
  HTFAKE          = "/your_host_name/cgi-bin"
  HTMLHOST        = "your_host_name"
  HTMLHOST_ALT    = ""
  HTMLLOC         = "your_host_name"
  PASSWORD        = ""
  PROTOCOL        = "http"
  USERNAME        = "isfdb1"
  LEGACY_PASSWORDS= 1
  UNICODE         = "iso-8859-1"
  WIKILOC         = "your_host_name/wiki"

• Note that you will want to set LEGACY_PASSWORDS to 1. This will use the old md5 hashing algorithm when logging into your system. This will match the md5 algorithm used by create_user.py to create an account.
• 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 "localhost", e.g. "isfdb.org" if HTMLHOST is "www.isfdb.org".

2. Next edit INSTALLDIRS in the main source code directory:

  INSTALL_CGI     = Local CGI binary directory
  INSTALL_HTML    = Local HTML directory

3. Check the directory permissions on your INSTALL_CGI and INSTALL_HTML directories. You'll either need to do the install as a user who has permission to write there or you'll need to modify the permissions on the directories.

4. Then 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.

If you get errors about "SyntaxError: Missing parentheses in call to 'print'", you are probably using Python 3, which is currently unsupported as described above. You can see your current version of Python by running 'python --version'. If necessary, set up a new Python environment using a tool such as virtualenv e.g.

    # This example is on Fedora, which uses 3.11.4 by default
    isfdb-code-svn $ virtualenv --python=python2.7 py27venv
    ... output deleted ...
    isfdb-code-svn $ cd py27venv/
    py27venv $ python --version
    Python 3.11.4
    py27venv $ activate
    (py27venv) py27venv $ python --version
    Python 2.7.18

5. Save copies of your versions 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 the personal Linux setup without MediaWiki's PHP-based software, this is not possible. A Python script is provided to update the appropriate MediWiki tables to allow editing permissions. After everything is installed and you are able to view ISFDB Web pages, run the following command:

isfdb/scripts/create_user.py LoginName password

This will insert the login name and encrypted password into the correct tables. By default, the new user will be a moderator as well as a bureaucrat. If you want to create a non-privileged user, pass "0" as the third parameter.