forked from rho_n/hpr_generator
Merge pull request '[I87] Getting Started tutorial' (#89) from I87-Getting_Started_tutorial into main
Reviewed-on: rho_n/hpr_generator#89
This commit is contained in:
Roan Horning
commit
3b144ecaf5
202
GETTING_STARTED.md
Normal file
202
GETTING_STARTED.md
Normal file
@ -0,0 +1,202 @@
|
|||||||
|
# Clone the repository
|
||||||
|
|
||||||
|
If git is not installed on the operating system, please install it now
|
||||||
|
(see the git documentation for [instructions on installing git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)).
|
||||||
|
|
||||||
|
To retrieve the code from the repository on anhonesthost.net (a username and
|
||||||
|
password are required), run:
|
||||||
|
|
||||||
|
`git clone https://repo.anhonesthost.net/rho_n/hpr_generator.git`
|
||||||
|
|
||||||
|
To retrieve the code from the repository on gitlab.com, run:
|
||||||
|
|
||||||
|
`git clone https://gitlab.com/roan.horning/hpr_generator.git`
|
||||||
|
|
||||||
|
On success, an "hpr_generator" directory will be created in the folder from
|
||||||
|
which the clone command was executed containing a local copy of the git repository.
|
||||||
|
|
||||||
|
# Install required Perl modules
|
||||||
|
|
||||||
|
Installing the Perl modules is the most finicky part of the installation process.
|
||||||
|
The needed Perl modules can be found using the operating system's package
|
||||||
|
manager or using the modules found in the
|
||||||
|
[Comprehensive Perl Archive Network (CPAN)](https://www.cpan.org/).
|
||||||
|
|
||||||
|
## Installing modules on Debian based Linux distributions
|
||||||
|
|
||||||
|
Run command (tested on Debian 11):
|
||||||
|
|
||||||
|
```
|
||||||
|
apt install libconfig-std-perl \
|
||||||
|
libtemplate-perl \
|
||||||
|
libtemplate-plugin-dbi-perl \
|
||||||
|
libdbd-sqlite3-perl libdate-calc-perl \
|
||||||
|
libtie-dbi-perl
|
||||||
|
```
|
||||||
|
|
||||||
|
## Using CPAN to install the modules
|
||||||
|
|
||||||
|
A cross platform method to install the needed modules is the Perl CPAN application.
|
||||||
|
Make sure both the [make](https://www.gnu.org/software/make/manual/make.html)
|
||||||
|
command and the [cpan](https://perldoc.perl.org/CPAN) command are available.
|
||||||
|
Install them using the operating system's package manager, or from source.
|
||||||
|
|
||||||
|
Run commands:
|
||||||
|
|
||||||
|
```
|
||||||
|
cpan Config::Std
|
||||||
|
cpan Template
|
||||||
|
cpan Template::Plugin::DBI
|
||||||
|
cpan DBD::SQLite
|
||||||
|
cpan Date::Calc
|
||||||
|
cpan Tie::DBI
|
||||||
|
```
|
||||||
|
|
||||||
|
# Create the HPR database
|
||||||
|
|
||||||
|
The hpr_generator relies on information from a database to generate many of the
|
||||||
|
files for the website (for example: index.html, series/index.html,
|
||||||
|
hpr_mp3.rss, etc). This data is available from a MySQL dump file found on
|
||||||
|
hackerpublicradio.org at URL "https://www.hackerpublicradio.org/hpr.sql".
|
||||||
|
|
||||||
|
The first step is to download the hpr.sql file. This can be done using your
|
||||||
|
browser, or by running one of the following commands:
|
||||||
|
|
||||||
|
`curl https://www.hackerpublicradio.org/hpr.sql --output ./hpr.sql`
|
||||||
|
|
||||||
|
or
|
||||||
|
|
||||||
|
`wget --directory-prefix=./ https://www.hackerpublicradio.org/hpr.sql`
|
||||||
|
|
||||||
|
## 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
|
||||||
|
is used for this conversion. First remove the lines from hpr.sql that
|
||||||
|
mysql2sqlite can't handle:
|
||||||
|
|
||||||
|
`sed '/^DELIMITER ;;/,/^DELIMITER ;/d' < ./hpr.sql > ./hpr-sqlite.sql`
|
||||||
|
|
||||||
|
Next run the mysql2sqlite script piping its output into the sqlite3
|
||||||
|
program which creates the hpr.db file:
|
||||||
|
|
||||||
|
`./utils/mysql2sqlite ./hpr-sqlite.sql | sqlite3 ./hpr.db`
|
||||||
|
|
||||||
|
For convenience, the update-sqlite-db.sh script in the utils directory
|
||||||
|
automates the above steps (including downloading the hpr.sql file).
|
||||||
|
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 the site-generator
|
||||||
|
|
||||||
|
Run the site generator form the hpr_generator directory:
|
||||||
|
|
||||||
|
```
|
||||||
|
./site-generator --all
|
||||||
|
```
|
||||||
|
|
||||||
|
This will generate all the files for the website. For more examples and to see
|
||||||
|
all available options run:
|
||||||
|
|
||||||
|
```
|
||||||
|
./site-generator --help
|
||||||
|
```
|
||||||
@ -35,7 +35,8 @@ Static web page generator for the Hacker Public Radio website.
|
|||||||
* Tie::DBI
|
* Tie::DBI
|
||||||
* DBD::SQLite or DBD:mysql
|
* DBD::SQLite or DBD:mysql
|
||||||
* Date::Calc
|
* Date::Calc
|
||||||
|
* See the Getting Started tutorial (GETTING_STARTED.md) for more details on
|
||||||
|
installing the HPR generator.
|
||||||
## Usage
|
## Usage
|
||||||
Generate two specific pages:
|
Generate two specific pages:
|
||||||
`site-generator index about`
|
`site-generator index about`
|
||||||
|
|||||||
54
utils/update-hpr-db.sh
Executable file
54
utils/update-hpr-db.sh
Executable file
@ -0,0 +1,54 @@
|
|||||||
|
#!/bin/bash -
|
||||||
|
#===============================================================================
|
||||||
|
#
|
||||||
|
# FILE: update-hpr-db.sh
|
||||||
|
#
|
||||||
|
# USAGE: ./update-hpr-db.sh
|
||||||
|
#
|
||||||
|
# DESCRIPTION: Download MySQL hpr.sql file and create SQLite3 file
|
||||||
|
#
|
||||||
|
# OPTIONS: ---
|
||||||
|
# REQUIREMENTS: lib_utils.sh
|
||||||
|
# BUGS: ---
|
||||||
|
# NOTES: ---
|
||||||
|
# AUTHOR: Roan "Rho`n" Horning (roan.horning@gmail.com)
|
||||||
|
# ORGANIZATION:
|
||||||
|
# CREATED: 03/05/2023 07:21:29 PM
|
||||||
|
# REVISION: ---
|
||||||
|
# LICENSE: GNU AGPLv3
|
||||||
|
#
|
||||||
|
# This program is free software: you can redistribute it and/or modify
|
||||||
|
# it under the terms of the GNU Affero General Public License as published by
|
||||||
|
# the Free Software Foundation, either version 3 of the License, or
|
||||||
|
# (at your option) any later version.
|
||||||
|
#
|
||||||
|
# This program is distributed in the hope that it will be useful,
|
||||||
|
# but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||||||
|
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
||||||
|
# GNU Affero General Public License for more details.
|
||||||
|
#
|
||||||
|
# You should have received a copy of the GNU Affero General Public License
|
||||||
|
# along with this program. If not, see <https://www.gnu.org/licenses/>.
|
||||||
|
#
|
||||||
|
#===============================================================================
|
||||||
|
|
||||||
|
set -o nounset # Treat unset variables as an error
|
||||||
|
|
||||||
|
BASEDIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
|
||||||
|
|
||||||
|
#
|
||||||
|
# Load library functions
|
||||||
|
#
|
||||||
|
LIB="$BASEDIR/lib_utils.sh"
|
||||||
|
[ -e $LIB ] || { echo "Unable to load functions.\n$LIB not found."; exit; }
|
||||||
|
source $LIB
|
||||||
|
|
||||||
|
WORKING_DIR=`make_working_dir`
|
||||||
|
|
||||||
|
download_hpr_sql $WORKING_DIR
|
||||||
|
|
||||||
|
make_hpr_sqlite_db $WORKING_DIR
|
||||||
|
|
||||||
|
copy_to_public_dir $WORKING_DIR `pwd`
|
||||||
|
|
||||||
|
clean_working_dir $WORKING_DIR
|
||||||
Loading…
Reference in New Issue
Block a user