Project Hirtius -- Upgrading an Existing Hirtius Instance
=========================================================
(pan - 10/06/2024)
Important note: The steps below describe a generic upgrade process suitable
for a Hirtius installation that followed all the
recommendations outlined in our INSTALL document. If your
installation deviates from these guidelines, please adapt the
upgrade steps to match.
Moreover, the deployment of future new features may
require additional steps not covered here. If this occurs,
the extra steps will be documented in due course.
1./ Before you begin
----------------
a. Notify your users
.................
Tell your users ahead of time about the application downtime your planned
upgrade will entail. The easiest way to do so is to click on the "email all"
link provided on the "Users and Authentication" page.
b. Identify your current database schema version
.............................................
In the context of this upgrade, further down, you may need to apply one or
more scripts that will bring your database schema in line with the new
version of the application code. In order to determine exactly which database
upgrade scripts need applying, you first need to identify your current
database schema version.
There are (at least) 3 ways for you to do this, but the easiest one is:
- login on the Hirtius application web-based interface as a user with
'admin' privileges
- go to the "Hirtius DB administration interface" by clicking on your login
name in the upper left corner
- make a note of the number printed on the line that reads "Database schema
version"
The other 2 ways are to look for the expected database schema version in the
global definitions file (definitions.inc), or to query it from the database
itself (column 'db_info.schema_version').
c. Backup your data
................
Before you begin with the upgrade process proper, you should close user access
to the application (to prevent further modification of the data) and make sure
you have a reliable backup of your current installation and the data it
contains.
At the very least, perform the following three tasks:
- stop Apache on the server where the Hirtius HTML front-end is installed:
----------------------<cut>--------------------------
# systemctl stop apache2.service
----------------------<cut>--------------------------
- dump the current contents of your 'hirtius' database:
----------------------<cut>--------------------------
$ mysqldump -u hirtius -p hirtius | gzip > HirtiusDB_before.sql.gz
----------------------<cut>--------------------------
- archive your current Hirtius application folder:
----------------------<cut>--------------------------
# cd /srv/www/htdocs
# tar -cvzf hirtius_app_before.tar.gz hirtius/
----------------------<cut>--------------------------
As always, please adapt the above commands to the specificities of your site,
and keep the generated archives in a safe place.
d. Keep a copy of your Hirtius definitions file around
...................................................
Of course, once you have performed the step described just above, you can be
confident that your current definitions file will be kept, along with the rest
of your application and data.
But since a step further down will require easy access to it, it also makes
sense to keep a copy right at hand. To do so, you could type:
----------------------<cut>--------------------------
# cd /srv/www/htdocs/hirtius
# cp definitions.inc definitions.inc.OLD
----------------------<cut>--------------------------
2./ Upgrade the application
-----------------------
The new version of the Hirtius application is located in a sub-folder of the
distribution archive. To prepare for installation, you should unpack that
archive in a working directory. Once done, simply copy the 'hirtius/'
sub-folder over your current installation:
----------------------<cut>--------------------------
# tar -cvf - hirtius/ | ( cd /srv/www/htdocs/ ; tar -xf - )
----------------------<cut>--------------------------
Change ownership of the tree to your webserver user and group (wwwrun:www):
----------------------<cut>--------------------------
# cd /srv/www/htdocs/
# chown -R wwwrun:www hirtius/
----------------------<cut>--------------------------
Remove any right to 'other' (to protect DB credentials and access
information):
----------------------<cut>--------------------------
# chmod -R o-rwx hirtius/
----------------------<cut>--------------------------
All files and directories should be flagged R/O even for the owner and group,
except for the "reports/" subdir, that should be writeable by the Apache
server:
----------------------<cut>--------------------------
# chmod -R ug-w hirtius/
# chmod -R ug+w hirtius/reports/
----------------------<cut>--------------------------
3./ Upgrade your database schema
----------------------------
The new version of the Hirtius application you just installed may require
a different database schema version from the one you used earlier.
Check this by comparing the value for '$exp_db_schema_version' in the NEW
./definitions.inc file with the value you looked up earlier in step 1.b.
Once you have determined that a schema upgrade was required, go to the
sub-folder called 'docs/db_update/' in the distribution archive, and apply
ALL REQUIRED UPDATE SCRIPTS IN SEQUENCE!
For instance, to go from schema 41 to 43, you should execute the following
commands in that order:
----------------------<cut>--------------------------
$ mysql -u hirtius -p hirtius < db_v41_to_v42.sql
$ mysql -u hirtius -p hirtius < db_v42_to_v43.sql
----------------------<cut>--------------------------
WARNING: these SQL scripts don't verify that the current database schema
version is the expected one before updating the schema, so please perform
all necessary checks yourself.
a. Version-specific upgrade notes
..............................
43 -> 44: If you already had existing projects in your database and their
contents language is not English, these values would need to be
adjusted manually using SQL statements AFTER having run this upgrade
script.
Example (most of your projects are written in French, but a couple
are in Italian):
> UPDATE projects SET content_lang = 'fr';
> UPDATE projects SET content_lang = 'it' WHERE obj_id IN (12, 13);
49 -> 50: The DB schema upgrade script ends with a set of 3 SELECT queries
designed to identify all Events and Titles whose "era" column will
need to be checked individually. Run these queries manually and keep
the resulting report in a safe place as you will need it later (at
step 7. below).
4./ Re-apply local configurations to definitions file
-------------------------------------------------
You should now re-apply all applicable local configuration items to the new
version of the global definitions file.
Do this either by editing ./definitions.inc and ./definitions.inc.OLD side
by side, or by using the merge tool of your choice. Please note that the
internal organisation of that file may change between versions.
Also remember to review the latest version of the file for any new
user-configurable parameter.
5./ System-level version-specific upgrade notes
-------------------------------------------
a. 1.x -> 1.03
...........
- Adapt mode and ownership on the Apache password file used by Hirtius
(typically '/etc/webusers'): it should now be owned 'wwwrun:www' and
mode 640.
- Remove the entries related to user 'wwwrun' and to 'htpasswd2' utility
from the 'sudo' configuration file.
b. 1.x -> 1.04
...........
- All new user accounts created after the upgrade will use the stronger
'bcrypt' algorithm for password hashing by default. But if you want
existing accounts to upgrade to it as well, you should ask these users
to change their password (you can use the "email all" link on the
Users List page to do so). Older hashing algorithms are still supported,
and Apache will evaluate the appropriate algo to use for each line in the
password file individually, so this upgrade should cause no disruption to
existing users.
c. 1.x -> 1.06
...........
- Install the newly required PHP module: 'php7-intl'
6./ Restart and test the application
--------------------------------
Now that the main part of the upgrade proper has been performed, restart
the Apache server to allow access to the Hirtius application:
----------------------<cut>--------------------------
# systemctl start apache2.service
----------------------<cut>--------------------------
You should then login and verify that the application performs as expected,
that all your data is still accessible, etc. Please read the Changelog entries
for all versions between your old one and the one you just installed to
understand the impacts of the changes and determine which part of the
application may need more detailed testing based on your own usage scenario.
7./ Version-specific data migration steps
-------------------------------------
a. 1.x -> 1.06
...........
- take the report(s) generated by the last 3 SELECT statements at step 3.a
above (they list all Events and Titles whose era could not be determined
automatically). Open each object in edition mode and determine (based on
the source of your information and all relevant documentation) in which era
the recorded date was originally expressed. Update the object record
accordingly (this will cause the JDN value to be recomputed if needed).
Make sure to update ALL identified records (events and titles) in this way,
as a NULL value for era where the respective date is set would cause the
next step to fail.
- install, run once, then remove the purpose-built 'date_keys_JG_db_update.php'
script:
* copy it from './docs/db_update/' in the distribution archive to your
Hirius Web folder
* make sure it is owned 'root:www', mode 640
* run it by pointing your browser at the following URL and authenticating
as an admin-level user:
<http://$url_base/date_keys_JG_db_update.php>
(adapt '$url_base' -- no further confirmation will be requested)
* when done, remove the script from your Hirius Web folder (the goal is only
to avoid needless clutter -- if run a 2nd time, the script should simply
fail to find any record needing to be modified)
The purpose of this script is to recompute a correct JDN value for all
Events and Titles that were automatically assigned the Julian era based on
their date at step 3.a above.
8./ Cleanup & Sanity Check
----------------------
Once you are confident your applications runs as expected and the new features
are available, you should remove the copy of your old global definitions file:
----------------------<cut>--------------------------
# cd /srv/www/htdocs/hirtius
# rm definitions.inc.OLD
----------------------<cut>--------------------------
You should also run the Database Sanity Check (available from the Hirtius DB
administration interface) and correct any error that it might report.
9./ Upgrade helper scripts
----------------------
Additionally, you should review the contents of the 'scripts/' folder and
determine whether any of them has been updated and needs to be copied on top
of the older version or is a new entry that may need to be deployed. Please
refer to the accompanying README file for more details on the scripts roles,
where you might want to install them, how to use them, and so on.
You should also refer to the main INSTALL document to determine whether
new dependencies (such as Perl modules or external utilities) need be
installed to support the updated helper scripts.
Also remember to review the latest version of the template global
configuration file ('hirtiusadmrc.tmpl') for any new user-configurable
parameter that would need to be merged into your user's local copy
('~/.hirtiusadmrc').
|
