From d617cf01d39dfcefe536b82a55d5acf760eecef8 Mon Sep 17 00:00:00 2001 From: Paul Jewell Date: Tue, 28 Jan 2025 09:22:05 +0000 Subject: [PATCH] I250 - Clarify local SQL database setup. - Add MySQL information to GETTING_STARTED.md. - Recommend SQLite over MySQL for local processing. --- GETTING_STARTED.md | 14 +++++++++- README.md | 69 ++++++++++++++++++++++++++-------------------- 2 files changed, 52 insertions(+), 31 deletions(-) diff --git a/GETTING_STARTED.md b/GETTING_STARTED.md index 6825d43..ada2d7b 100644 --- a/GETTING_STARTED.md +++ b/GETTING_STARTED.md @@ -81,7 +81,8 @@ or `wget --directory-prefix=./ https://www.hackerpublicradio.org/hpr.sql` -## Creating an SQLite database file +You can process the file using SQLite, or MySQL as you prefer. SQLite is the recommended option for local processing, but instructions are given for both options: +## Option 1: Creating an SQLite database file The SQL of the hpr.sql file must be converted from MySQL specific statements to SQLite specific statements. The mysql2sqlite script found in the utils directory @@ -101,6 +102,17 @@ From the root of the local hpr_generator repository run: `./utils/update-sqlite-db.sh` +## Option 2: Creating a MySQL database file + +The SQL code in the hpr.sql file needs to be loaded into a local database: +* Create database hpr_hpr in the MySQL server from HPR dump file. + - ``sudo mysql --host=localhost < hpr.sql`` +* Create a user that will be used by the site-generator. + - Suggested username: hpr-generator + - ``CREATE USER 'hpr-generator'@'localhost' IDENTIFIED BY '';`` +* Limit the user's privileges to EXECUTE and SELECT + - ``GRANT SELECT ON hpr_hpr.* TO 'hpr-generator'@'localhost';`` + - ``GRANT EXECUTE ON `hpr_hpr`.* TO 'hpr-generator'@'localhost';`` # Configure the site-generator In your favorite text editor, open the site.cfg file found in the root of the diff --git a/README.md b/README.md index 190607f..c27ea13 100644 --- a/README.md +++ b/README.md @@ -1,40 +1,46 @@ # hpr_generator + Static web page generator for the Hacker Public Radio website. ## Installation -* Clone or download this repository -* Download the database and load into SQLite - * Create the sqlite3 database from the hpr.sql MySQL dump file available on - hackerpublicradio.org. The default name for the database file is "hpr.db" - and should be located in the root of the project directory. The name and - location can be set in the site.cfg file. - * An "update-hpr.sh" helper script is available in the utils directory. This - script will download the hpr.sql file, convert it to the SQLite hpr.db file, - and regenerate the website using the site-generator. - 1. `cd` into the root of the project directory - 2. Run `./utils/update-hpr.sh` - * SQLite v3.8.3 or greater is recommended. CTE WITH clauses are used in some template queries. Must convert WITH - clauses to sub-queries when using earlier versions of SQLite. -* Install the needed Perl modules using preferred method (distribution packages, CPAN, etc.) - * Getopt::Long - * Pod::Usage - * Config::Std - * Template - * Template::Plugin::File - * Template::Plugin::DBI - * Template::Plugin::Date - * Template::Plugin::HTML::Strip - * DBI - * Tie::DBI - * DBD::SQLite or DBD::mysql - * Date::Calc - * Text::CSV_XS - * HTML::Entities -* See the [Getting Started](GETTING_STARTED.md) tutorial for more details on +* Clone or download this repository +* Download the database and load into SQLite or mySQL + SQLite is the preferred database management tool for local generation. The tools available in the utils directory of this repository support ease of use with SQLite. However, you can also use mySQL locally if you wish. Instructions are provided for both: + * SQLite + - Create the sqlite3 database from the hpr.sql MySQL dump file available on hackerpublicradio.org. The default name for the database file is "hpr.db" and should be located in the root of the project directory. The name and location can be set in the site.cfg file. + - An "update-hpr.sh" helper script is available in the utils directory. This script will download the hpr.sql file, convert it to the SQLite hpr.db file, and regenerate the website using the site-generator. 1. `cd` into the root of the project directory 2. Run `./utils/update-hpr.sh` + + Note: SQLite v3.8.3 or greater is recommended. CTE WITH clauses are used in some template queries. Must convert WITH clauses to sub-queries when using earlier versions of SQLite. + * mySQL + - Create database hpr_hpr in the MySQL server from HPR dump file. - `sudo mysql --host=localhost < hpr.sql` + - Create a user that will be used by the site-generator. - Suggested username: hpr-generator: + - `CREATE USER 'hpr-generator'@'localhost' IDENTIFIED BY '';` + - Limit the user's privileges to EXECUTE and SELECT: + - ``GRANT SELECT ON hpr_hpr._ TO 'hpr-generator'@'localhost';` + - `GRANT EXECUTE ON `hpr_hpr`.\* TO 'hpr-generator'@'localhost';`` +* Install the needed Perl modules using preferred method (distribution packages, CPAN, etc.) + + - Getopt::Long + - Pod::Usage + - Config::Std + - Template + - Template::Plugin::File + - Template::Plugin::DBI + - Template::Plugin::Date + - Template::Plugin::HTML::Strip + - DBI + - Tie::DBI + - DBD::SQLite or DBD::mysql + - Date::Calc + - Text::CSV_XS + - HTML::Entities + +- See the [Getting Started](GETTING_STARTED.md) tutorial for more details on installing the HPR generator. ## Usage + Generate two specific pages: `site-generator index about` @@ -45,12 +51,14 @@ Generate pages based on the same template: `site-generator correspondent=1,3,5..10` ## Support + Please [submit an Issue](https://repo.anhonesthost.net/HPR/hpr_generator/issues), and add the label "**Help Request**" for help running or installing the site-generator. For discussing HPR site generation in general, please [submit an Issue](https://repo.anhonesthost.net/HPR/hpr_generator/issues) and add the label "**General Discussion**". ## Contributing + Happy to take any contributions or suggestions. To contribute code or documentation, please create a fork of the project and [submit a pull request](https://repo.anhonesthost.net/HPR/hpr_generator/pulls) or send a patch. If an issue exists that is related to your patch, please assign the issue to yourself, or if it is already assigned to someone else, please coordinate with them to minimize duplicated efforts. @@ -62,9 +70,10 @@ To make a suggestion, please [submit an Issue](https://repo.anhonesthost.net/HPR and add the label "**Feature Request**". ## Authors and acknowledgment + * Roan "Rho`n" Horning * Dave Morriss * gordons * Ken Fallon * norrist - +* Paul Jewell (paulj)