Instructions for updating a production JMdictDB server

June 2020

This procedure describes how to apply the 20.06.01 changes to an existing JMdictDB server instance. If you are installing JMdictDB for the first time please see the Installation Guide.

See the 2020-06-changes document for a summary of major changes.

1. Get the current version of the JMdictDB code

The updates applied by this procedure are present in both the edrdg and master branches. However the master branch may have additional newer changes. See section 4.1 of the Installation Guide for information on the differences between the two branches.

If you have an a checkout of JMdictDB already, you can cd to that directory and do a git pull.

Otherwise you can clone the JMdictDB repository:

git clone https://gitlab.com/yamagoya/jmdictdb.git jmdictdb

or, you can download a tar or zip archive at:

(The download button is just to the left of the green Clone button) and unpack it in a convenient directory.

For exposition we will assume that you have done this in your home directory and the JMdictDB code in in ~/jmdictdb/. Make the appropriate substitutions in the following if you’ve done this in some other directory.

2. Apply database updates

You may wish to backup your current versions of databases first.

Note the database update script are now in db/updates/ rather than patches/ as they were formerly. Substitute the name of the database to be updated for <database> below. Repeat for each database you want to update.

$ psql -d jmdict -U <database> -f db/updates/029-000000.sql
$ psql -d jmdict -U <database> -f db/updates/029-835781.sql
$ psql -d jmdict -U <database> -f db/updates/030-a921f4.sql

The version checks in each update script will produce a message like:

err
-----

This is not an error but an artifact of the version checking code. If there is an actual version mismatch, an error message like:

Database at wrong update level...

will be generated and the script aborted.

The script 029-835781.sql may produce a NOTICE message:

table "freq_tmp" does not exist, skipping

which is innocuous.

From the time you do this until you finish step 3 below, anyone accessing the JMdictDB server will likely experience errors.

3. Deploy the JMdictDB code

3.1. Install the updated software

Change to directory where you’ve installed the JMdictDB web components (the parent directory the directory where you serve the CGI scripts from.) For the purpose of exposition we’ll assume it is /usr/local/jmdictdb/ and that you want to continue to use this directory..

$ cd /usr/local/jmdictdb/

Move the old cgi-bin and lib directories out of the way since they contain a lot of old, no longer relevant files. 'make' will create new, fresh versions.

$ mv cgi-bin cgi-bin-old
$ mv lib lib-old

Install the updated jmdictdb software from your source directory.

$ cd ~/jmdictdb/

The following 'make' command needs to be done as root. You may have 'sudo' setup for this. Or just do it from a root login. It will install a python package containing the files that used to be in the lib/ directory, into some standard, system-wide location where python stores such things. It will also install the command line programs (entrs2xml.py, et.al.) into /usr/local/bin/. The web components (CGI scripts, css files, etc) are installed by default into /usr/local/jmdictdb.

# sudo make WEBROOT=/usr/local/jmdictdb install-sys

Without the override of the WEBROOT variable, 'make' would have installed the web components into the default location of /var/www/jmdictdb.

3.2 Migrate the config and log files
# cd /usr/local/jmdictdb/lib/

I recommend that you create two files: config.ini containing the bulk of the configuration settings, and config-pvt.ini containing the database access credentials (the [db_*] sections). The former can be world-readable but the latter should be readable by only the maintainer and the web server.

Refer to the config-sample.ini and config-pvt-sample.ini for descriptions of the syntax and settings in the config files. Note that config.ini need only contain settings whose values differ from the default values described in config-sample.ini.

The default location for the CGI logfile is now lib/jmdictdb.log (it was formerly cgi-bin/jmdictdb.log) but the location can be changed by a configuration setting. Wherever you place it note that:

  • You must create it if you want logging, it won’t be automatically created.

  • It must be writable by the web server process owner.

If you have any other added files (e.g., a robots.txt file), copy them from the cgi-bin directory to the new one.

At this point the production JMdictDB web service should be back to normal.

4. Followup and cleanup

Update any scripts that run jmdictdb command line programs (eg entrs2xml.py) to use the versions in /usr/local/bin/.

If you have any scripts that run bulkupd.py, in addition to changing them to use the /usr/local/bin/ version you may also wish to change them to take advantage of enhancements described in 2020-06-changes although they should continue to work with no changes.

If you have a script that rotates the jmdictdb.log file it will need updating since the log file location changed from /usr/local/jmdictdb/cgi-bin/ to …​/jmdictdb/lib/.

At this point your ~/jmdictdb/ directory is no longer needed by the installed jmdictDB server. You may delete it if you wish or use it for development activities.

You can also delete the cgi-old/ and lib-old/ directories from /usr/local/jmdictdb/ now.