From 97a5d4ebbda0f89f79bdbc33cbbd1fc7ac25fe08 Mon Sep 17 00:00:00 2001 From: Roan Horning Date: Tue, 7 Mar 2023 19:09:33 -0500 Subject: [PATCH] Add instructions for configuring the site-generator --- GETTING_STARTED.md | 98 +++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 97 insertions(+), 1 deletion(-) diff --git a/GETTING_STARTED.md b/GETTING_STARTED.md index d223196..998e829 100644 --- a/GETTING_STARTED.md +++ b/GETTING_STARTED.md @@ -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 \ meta-data tag in the \ 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://] +``` +Below the #baseurl comment line add: + +``` +baseurl: file:///hpr_generator/public_html +``` + +Replace \ 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 \ No newline at end of file