From 97a5d4ebbda0f89f79bdbc33cbbd1fc7ac25fe08 Mon Sep 17 00:00:00 2001
From: Roan Horning <roan.horning@gmail.com>
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 \<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
\ No newline at end of file