Skip to content

Setting Up IFDB Without Docker

Jump to bottom
Dan Fabulich edited this page Jan 26, 2021 · 3 revisions

The easiest way to set up a developer environment for IFDB is to use the provided Docker environment. But perhaps you'd prefer to do it by hand. This guide is for you.

This guide will get out of date fast

Confirm that there have been no major changes in Dockerfile, docker-compose.yml or the .htaccess file since this date: Jan 26, 2021

(And if you do feel the need to update this wiki, increment that date!)

Routing via .htaccess

The IFDB code base is implemented in PHP, and assumes that you're going to run it in Apache. It includes an .htaccess file that does a lot of high magic.

<FilesMatch "^[^.]+$">
  ForceType application/x-httpd-php
</FilesMatch>

<FilesMatch "\.php$">
  Order Deny,Allow
  Deny from All
</FilesMatch>

RewriteEngine on
Options FollowSymLinks
RewriteBase /

RewriteCond %{HTTPS} !=on
RewriteCond %{HTTP_HOST} ^ifdb.org$ [OR]
RewriteCond %{HTTP_HOST} \.ifdb.org$
RewriteRule ^(.*)$ https://%{HTTP_HOST}%{REQUEST_URI} [L,R=301,NE]

RewriteRule ^$ home [L]
RewriteRule ^index$ home [L]
RewriteRule ^index\.htm$ home [L]
RewriteRule ^index\.html$ home [L]

That says:

  1. Any URLs that don't contain a dot (e.g. /home or /search) should be executed as PHP files.
  2. Don't allow users to navigate directly to any PHP files, e.g. dbconnect.php
  3. Redirect http://ifdb.org to https://ifdb.org
  4. When the user requests /, /index, /index.htm or /index.html, show the /home page in its place.

Configuring Apache

IFDB assumes that it's being hosted at the root of its domain. Set up a name-based virtual host in Apache, allowing .htaccess to override all settings. Here's a sample Apache configuration file.

```
<VirtualHost *:80>
ServerName ifdbdev
DocumentRoot "/home/YOURUSERNAME/ifdb/www"
<Directory /home/YOURUSERNAME/ifdb/www>
    Options Indexes FollowSymLinks
    AllowOverride All
    Require all granted
</Directory>
</VirtualHost>
```

Furthermore:

  • You'll need to enable mod_rewrite with a2enmod rewrite.
  • You'll need mysqli and php-gd enabled in your PHP installation. On most machines, those are enabled by default, but the Docker instance has to apt-get install -y zlib1g-dev libpng-dev libjpeg-dev, then configure gd using the --with-jpeg parameter and install gd separately.

Troubleshooting Apache

If you're seeing a directory listing when you try to view your site, and mod_rewrite is enabled, Apache is probably not allowing that .htaccess file to do its thing.

  • Check Apache's error logs.
  • If you don't see any errors, Apache is probably not honoring the .htaccess file. The AllowOverride All line in the <VirtualHost> sample above is intended to enable that.
  • To test whether Apache is honoring .htaccess, deliberately add an invalid line like BlahBlah Debugging to the www/.htaccess file. If Apache is honoring the .htaccess file, it should log an error about your invalid line. If you don't see any errors when you add an invalid line, then Apache isn't even looking at the .htaccess file, indicating that there's a problem in the way you set up your <VirtualHost> configuration.

Setting up MariaDB / MySQL

IFDB was written against good old MySQL 5, but it works with MariaDB 10. The docker-compose.yml requests the current latest version of MariaDB 10, currently 10.6.

Note that IFDB does not work with the current latest MySQL 8, which uses ICU regular expressions instead of MySQL 5 "Henry Spencer" regexes. https://dev.mysql.com/doc/refman/8.0/en/regexp.html#regexp-compatibility

For example, if you just change the mariadb line in docker-compose.yml to mysql:8, searches by author fail http://localhost:8080/search?searchfor=author%3AEmily+Short because the query includes this "Henry Spencer" regex: author like '%Emily Short%' or author rlike [[:<:]]E.*[[:space:]]+Short[[:>:]]'

We need a few backward compatibility settings to run on the current latest versions of MySQL 5 or MariaDB 10:

  • Modern versions of MySQL/MariaDB come with a bunch of sql_mode settings designed to protect us from ourselves. To circumvent these protections, you'll need to run set global sql_mode = ''; as the MySQL root user. (The Docker configuration does that for you automatically.)
  • IFDB assumes that the database is using ISO-8859-1 latin1, which is the default in MySQL 5, but apparently not the default in MariaDB 10. (MariaDB defaults to UTF-8 utf8mb4. Our Docker file launches MariaDB with --character-set-server=latin1 --collation-server=latin1_german2_ci to get the defaults we need.

Once you've got MariaDB/MySQL up and running, you can run ./prepare_dev_environment.sh to generate SQL schema scripts in the initdb directory and generate a www/local-credentials.php file. (That script has no dependencies on Docker.) Manually run the scripts in the initdb directory to create and initialize the ifdb database.

Clone this wiki locally