Add instructions for configuring the site-generator

This commit is contained in:
Roan Horning 2023-03-07 19:09:33 -05:00
parent b420453abd
commit 97a5d4ebbd
Signed by: rho_n
GPG Key ID: 234AEF20B72D5769

View File

@ -87,5 +87,101 @@ From the root of the local hpr_generator repository run:
`./utils/update-sqlite-db.sh`
# Configure the site-generator
In your favorite text editor, open the site.cfg file found in the root of the
"hpr_generator" folder. Full details about options for configuring the site.cfg
file are found in the comments within the file.
## Configuring the database connection
Any database supported by the Perl:DBI and Perl::DBD modules can be used with
the site-generator program. Currently the hpr_generator project works with
a MySQL or SQLite database.
Find the [DBI] section of the file. It should look like the following
```
[DBI]
# Configuration settings for SQLite
#database: sqlite
#driver: dbi:SQLite:hpr.db
#user: (not used - leave blank)
#password: (not used - leave blank)
# Configuration settings for MySQL
#database: mysql
#driver: dbi:mysql:database=hpr_hpr:hostname=localhost
#user: hpr-generator (Suggested user with read-only privileges)
#password: ********* (Password for user)
```
### SQLite
Remove the comment character from the start of the database and driver
option lines:
```
# Configuration settings for SQLite
database: sqlite
driver: dbi:SQLite:hpr.db
#user: (not used - leave blank)
#password: (not used - leave blank)
```
The hpr.db section of the driver option `dbi:SQLite:hpr.db` is the path
to the sqlite file. The default assumes the hpr.db file is located in the same
directory as the site-generator.
### MySQL
Remove the comment character from the start of the database, driver,
user, and password option lines:
```
# Configuration settings for MySQL
database: mysql
driver: dbi:mysql:database=hpr_hpr:hostname=localhost
user: hpr-generator
password: *********
```
This assumes that the MySQL database service is available at the localhost
hostname, that the database name (hpr_hpr) is the database created from
the hpr.sql dump file or manually created by you, that the user (hpr-generator)
was added by you and has read rights to the hpr_hpr database, and that the
password (replace ********* with the actual password) matches the password set
for the hpr-generator database user.
## Configuring the website for viewing locally
For HTML links to work when viewing the files on your local machine using the
"file://" protocal (i.e. using the "Open..." command in your browser, each HTML
file must include a \<base\> meta-data tag in the \<head\> section of its
contents. To configure this in the site.cfg file, find the [root_template]
section. It should look like the following:
```
[root_template]
content: page.tpl.html
#baseurl: OPTIONAL [i.e. file://<full path to local website directory>]
```
Below the #baseurl comment line add:
```
baseurl: file://</path/to>/hpr_generator/public_html
```
Replace \<path/to\> with the full path to the hpr_generator directory. For
example: `file:///home/rho_n/development/hpr_generator/public_html`
## Configuring the website media file links
If you do not want to host all the media files (currently, audio files and
transcription files), you can configure the `media_baseurl` option. This can
be added to the [root_template] section of the site.cfg file. Suggested
external site is archive.org. To use this site add:
```
media_baseurl: https://archive.org/download/hpr$eps_id/
```
# Run site-generator