Project Hirtius -- Installation Instructions
============================================
(pan - 06/12/2023)
0./ Prerequisites
-------------
Platform: The following procedure is based on openSUSE Leap 15.4 64bit
--------- (which includes Apache 2.4.51 and PHP7), but any other modern
Linux distribution should work equally well (after translating
some paths and package names). *BSD should work as well. Windows
is untested (if you take that route, you're on your own -- I don't
use it so I can't help you. You've been warned).
Please note, that in order to support the widest range of international
characters, the application and its environment will be set up to support
UTF-8. The application also works well in ISO-8859/Latin1 mode, but using
it that way is no longer recommended.
Make sure the following software packages are installed and that their
base configuration is appropriate:
- apache2 (v2.4 or above)
- php7 (should work with any PHP v5.3.0 or above)
- mysql or mariadb (both server and client)
- php7-mysql
- php7-iconv
- php7-intl
- php7-mbstring
- apache2-mod_php7
- sudo
The accompanying scripts also require the following Perl modules:
- Config::Simple (most of them)
- Getopt::Long (most of them)
- DBI + DBD-MySQL (card_reminder, bulk_edit, slide_extract, upload_exif)
- MIME::Lite (card_reminder)
- Date::Manip (card_reminder)
- Encode (card_reminder)
- Math::Round (tray_gallery_gen)
- Image::ExifTool (exifmv, get_exif, upload_exif, tray_gallery_gen)
- HTML::Entities(*) (tray_gallery_gen)
*) part of HTML::Parser
And some of them may rely on the following external utilities:
- 'convert', part of the ImageMagick suite (tray_gallery_gen)
- 'curl' (slide_extract)
All of this may represent between 40MB and 210MB of extra software packages
to install on top of a default openSUSE deployment.
Create a Home Page in /srv/www/htdocs (call it 'index.html').
Enable and start Apache:
# systemctl enable apache2.service
# systemctl start apache2.service
Check that it works by accessing your newly created Home Page.
1./ Configure PHP
-------------
Edit /etc/php.ini (now /etc/php7/apache2/php.ini).
Set "file_uploads = On".
Set "upload_max_filesize = 2M" (or any other value that suits you).
Then, edit /etc/sysconfig/apache2 and add module 'php7' to the list defined
by the 'APACHE_MODULES' variable.
Restart the apache server to apply the new settings.
2./ Configure MySQL server to agree with PHP
----------------------------------------
Edit /etc/my.cnf
In the '[mysqld]' section, add or edit the following lines:
----------------------<cut>--------------------------
max_allowed_packet = 2M
default-character-set = utf8
init-connect = 'SET NAMES utf8'
----------------------<cut>--------------------------
(Please note: the 'default-character-set' and 'init-connect' variables have
been deprecated in more recent versions of the MySQL server. UTF-8 is now on
by default).
Enable and start the MySQL server to apply the new settings:
# systemctl enable mysql.service
# systemctl start mysql.service
Protect root access to your database server (replace 'new_password' with
a string of your own):
----------------------<cut>--------------------------
$ mysql -u root mysql
> UPDATE mysql.user SET Password = PASSWORD('new_password')
WHERE User = 'root';
> FLUSH PRIVILEGES;
----------------------<cut>--------------------------
Remove anonymous accounts (two are part of the default install):
----------------------<cut>--------------------------
$ mysql -u root mysql
> DELETE FROM mysql.user WHERE User = '';
----------------------<cut>--------------------------
3./ Allow the webserver to change the Apache password file
------------------------------------------------------
Copy the 'chhtuser' script provided in the ./scripts directory of the
distribution archive to /usr/local/bin.
Configure sudo (as root, using "visudo") to grant the webserver user
("wwwrun") the right to run as root with no password confirmation the
program it needs to manage the Apache password file:
- /usr/local/bin/chhtuser
Here are the statements needed in the sudo configuration file:
----------------------<cut>--------------------------
User_Alias WEBSERVER = wwwrun
Cmnd_Alias HTPASSWD = /usr/local/bin/chhtuser
WEBSERVER ALL = NOPASSWD: HTPASSWD
----------------------<cut>--------------------------
(The '\' character in the above is used for continuation and should
be typed as such in /etc/sudoers).
Please note: granting access to '/usr/bin/htpasswd2' through sudo is no
longer needed. This will now be managed through file permissions.
4./ Put the Apache password file in place
-------------------------------------
Create it as /etc/webusers.
Make sure it is owned by 'wwwrun:www' and mode 640.
Use htpasswd2 (as root) to create the intial 'admin' user account:
----------------------<cut>--------------------------
# htpasswd2 -c /etc/webusers admin
----------------------<cut>--------------------------
Memorise the password you will be requested to provide. You will need it at
step 13./ below ;-)
5./ Configure the hirtius directory in the web server conf
------------------------------------------------------
There are two ways to do this:
- as a new path below DocumentRoot on an existing server: see point a)
=> example URL: <http://myserver.localdomain.net/hirtius/>
- as a virtual Apache host: see point b)
=> example URL: <http://hirtius.localdomain.net/>
You have to choose either one of these two approaches (don't do both).
a) New path on an existing server
..............................
Go to '/etc/apache2/conf.d'.
Copy the provided './docs/hirtius.conf' there, and review its contents (at
least review the following values):
- Require ip: list networks that should be allowed to access your server.
Replace '<mysubnet(s)>' with your local subnet(s) (or "Require all granted"
if you don't want to apply any filtering).
b) Virtual Apache host
...................
First edit your local DNS zone and create an alias (CNAME) called "hirtius"
that points to your web server name. Something like:
----------------------<cut>--------------------------
hirtius IN CNAME webserverhost.localdomain.net.
----------------------<cut>--------------------------
Reload the zone when done.
Then go to '/etc/apache2/vhosts.d'.
Copy the provided './docs/hirtius_vh.conf' there, and review its contents (at
least review the following values):
- ServerAdmin: Virtual server administrator email address. Replace
'<mydomain>' with your local DNS domain name.
- ServerName: The fully-qualified host name the virtual server should
answer to. Replace '<mydomain>' with your local DNS domain name.
- Require ip: list networks that should be allowed to access your server.
Replace '<mysubnet(s)>' with your local subnet(s) (or "Require all granted"
if you don't want to apply any filtering).
c) In both cases:
..............
Restart the web server when done:
----------------------<cut>--------------------------
# systemctl restart apache2.service
----------------------<cut>--------------------------
6./ Create "hirtius" database and user
----------------------------------
Connect to the MySQL server as 'root'.
----------------------<cut>--------------------------
$ mysql -u root -p mysql
> CREATE DATABASE hirtius;
> GRANT ALL PRIVILEGES ON hirtius.* \
TO hirtius@localhost \
IDENTIFIED BY '...';
> FLUSH PRIVILEGES;
> exit
----------------------<cut>--------------------------
Replace "IDENTIFIED BY '...'" with a real password and keep note of it, as
will need to store it in Hirtius's main configuration file (see below).
If, like me, you prepare your Trays on a local workstation and not on the
server, you may wish to also grant access to the database from that machine,
possibly in read-only mode:
----------------------<cut>--------------------------
$ mysql -u root -p mysql
> GRANT SELECT ON hirtius.* \
TO hirtius@<mypc> \
IDENTIFIED BY '...';
> FLUSH PRIVILEGES;
> exit
----------------------<cut>--------------------------
Obviously, replace '<mypc>' in the SQL statement above by the hostname (fully-
qualified, ideally) of your local workstation.
7./ Create database structure
-------------------------
Connect to your newly created database as user 'hirtius'.
For a new, empty instance, use the database structure creation
script (./docs/create_hirtius_DB.sql):
----------------------<cut>--------------------------
$ mysql -u hirtius -p hirtius < create_hirtius_DB.sql
----------------------<cut>--------------------------
Then upload default content for system tables using the provided SQL script
(./docs/default_data.sql). This will also create the 'admin' account):
----------------------<cut>--------------------------
$ mysql -u hirtius -p hirtius < default_data.sql
----------------------<cut>--------------------------
Otherwise, upload an existing database contents (make sure its schema
version matches the expected value):
----------------------<cut>--------------------------
$ grep schema_version ./docs/create_hirtius_DB.sql
$ grep schema_version DB.sql
# if ok...
$ mysql -u hirtius -p hirtius < DB.sql
----------------------<cut>--------------------------
Please note: make sure your MySQL install has the InnoDB engine support
compiled in (you can check with "SHOW ENGINES;"). This is now the case by
default. You need to use this engine instead of the more basic "MyISAM" to
get transaction support.
8./ Install the Hirtius software
----------------------------
Unpack the software in a work area (somewhere below your home dir.), then
copy the hirtius/ subtree to a folder below your DocumentRoot (the one
defined above in section 5./).
----------------------<cut>--------------------------
# cd
# tar -xvzf hirtius-1.0.tar.gz
# cd hirtius/
# 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 ug+w hirtius/reports/
----------------------<cut>--------------------------
*) The "reports/" folder is where Hirtius will store user-generated raw
LaTeX reports. Configuring the client to turn these into PDF documents
is coved by the Hirtius HelpSet page titled "Requirements for Reporting
Module".
Once done, edit your server Home Page (created above in step 0./) and add a
link to the newly installed Hirtius application:
----------------------<cut>--------------------------
<a href="./hirtius/">Project Hirtius</a>
----------------------<cut>--------------------------
Please note that the exact link to create will depend on the choice you
made in section 5./ above (using a 'vhost' configuration or not) -- more
on this topic in section 13./ below.
9./ Customize configuration file
----------------------------
Check the main configuration file (./definitions.inc) for any needed
customisations.
At the very least, you should specify your own values for the following
variables in ./definitions.inc:
- $url_base: server FQDN
- $admin_email: Hirtius admin email address
- $mysql_passwd: password for MySQL 'hirtius' user account
- $webstore_base: FQDN for slides repository server
Some other values you may wish to customize:
- $debug: set it to the desired category, or combine them using the bitwise
'OR' operator (see example provided in the configuration file comments).
Debugging information will typically be included as HTML comments in the
generated pages, or as pop-up messages in JavaScript code
- $content_lang: language choice for the automatic content strings that
have been translated (currently supported choices are listed in the
./definitions.inc file [see $supported_langs], but it's easy for you to
add your own)
If you want to use a non-default value for either $tll or $tidlen, now is the
time to do so.
- $tll: controls the max. number of leaves per node in your INXtree. Its
default value (4) results in 1679615 leaves per node (4 positions in base36).
The value you select here should be a sub-multiple of the 'inxtree.tag'
column length (120 by default).
Examples (with 'inxtree.tag' at its default 120 char. length):
TLL: 3 (= 46655 leaves per node, 40 levels max.)
TLL: 4 (= 1679615 leaves per node, 30 levels max.)
TLL: 5 (= 60466175 leaves per node, 24 levels max.)
The length for column 'inxtree.tag' can be adjusted as well if needed, and
the application will pick up its new value automatically.
- $tidlen: controls the part of the in-tray address reserved for the Tray ID.
Defaults to 4. The rest (15 - $tidlen) can be used for the slot number, but
this value is often limited to 2 or 3 characters in practice.
10./ Create and populate the webstore
--------------------------------
On the web server, create a folder to hold the digital "trays" and their
contents (e.g. /data/forum/dias). Copy all digital "trays" below (you can
use the provided script called "publish" to do this, and it can also be done
later on). Then configure that directory for use by the web server. Edit
/etc/apache2/conf.d/hirtius.conf or /etc/apache2/vhosts.d/hirtius_vh.conf
(created above at step 5./ and add the following section (or customize the
one that I provided in the default configuration file):
----------------------<cut>--------------------------
Alias /dias "/data/forum/dias"
<Directory /data/forum/dias>
Options +Indexes +Multiviews +FollowSymLinks
IndexOptions FancyIndexing \
ScanHTMLTitles \
NameWidth=* \
DescriptionWidth=* \
SuppressLastModified \
SuppressSize
<RequireAny>
Require local
Require ip <mysubnet(s)>
</RequireAny>
</Directory>
----------------------<cut>--------------------------
Here as well, you can use "Require ip" to filter the networks that will be
granted access to this data: substitute '<mysubnet(s)>' with the network(s)
that should be granted access to your webstore (or replace that line with
"Require all granted" to not perform any filtering).
Restart the web server when done:
----------------------<cut>--------------------------
# systemctl restart apache2.service
----------------------<cut>--------------------------
11./ Schedule the library cards expiration reminder (optional)
---------------------------------------------------------
First copy ./scripts/card_reminder from the project archive to some place
where the Apache user (wwwrun) can read it, such as:
/srv/www/htdocs/hirtius/scripts
Then, as root, edit wwwrun's crontab file:
----------------------<cut>--------------------------
# crontab -e -u wwwrun
----------------------<cut>--------------------------
and add to it a line similar to the following one:
----------------------<cut>--------------------------
#...........................................Hirtius reminders
00 20 * * * /srv/www/htdocs/hirtius/scripts/card_reminder > \
/var/lib/wwwrun/log/card_reminder.log 2>&1
----------------------<cut>--------------------------
Please note: the '\' character at the end of the 2nd line in the snippet
above denotes the continuation of that line. It has to be removed if
copy-pasted, and the last 2 lines of the snippet must be merged in a
single one.
You will then need to create the /var/lib/wwwrun/log directory, and make sure
it belongs to 'wwwrun:www' (mode 755 should be fine).
12./ Install the external helper scripts (optional)
----------------------------------------------
Additionally, you may want to copy some of the contents of the scripts/
directory to a place like /usr/local/bin (see 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).
Please note: the scripts are accompanied by a global configuration file
provided as a template (called 'hirtiusadmrc.tmpl' and located inside the
distribution archive in the ./scripts/ directory). You should:
- copy this template in the home directory of any user that is likely to
use the scripts in question, renaming it to ~/.hirtiusadmrc
- edit its contents so that all variables defined therein match your local
environment. In particular, make sure that the values you set here are
in line with those defined in Hirtius' main configuration file, where
applicable (see point 9./ above)
13./ Access your new Hirtius application and start working
-----------------------------------------------------
Fire up your browser and connect to your newly installed application.
Depending on the choice you made in section 5./ above, replace <myserver>
or <myvhost> with your actual server FQDN in the following URL:
<http://<myserver>/hirtius/> OR <http://<myvhost>/>
Authenticate as 'admin', using the password you created at step 4./ above.
Start by running the Sanity Check ('Admin' | 'Run Sanity Check') to make sure
the newly created or imported database is healthy.
Then create a regular user for yourself. Depending on your internal policies,
make it an "administrator" or a regular "writer" (the main difference at this
stage is that administrators are allowed to delete objects whereas regular
users can only create and edit). If you decide to create more administrator
accounts, you may decide to disable the original one ('admin').
To make the best use of Project Hirtius, now would be a good time to read the
help pages that serve as introduction to the program:
- Concepts
- Projects Management Workflow
- Pictures Management Workflow
- Individuals Management Workflow
- Navigation Tips
All of these are linked from the top-level Help page. From Hirtius Home Page,
simply click "Help" in the top left corner and start reading. The Help Browser
also features a search interface that may assist you in locating the relevant
information.
Enjoy...
|
