== Introduction ==
h-source is web software that can be used to build a community of people that want to share their hardware information. It is based on the EasyGiant PHP framework (www.easygiant.org) and can be considered an EasyGiant application.
== Requirements ==
TODO: It is not clear what are the exact php modules required for the site to run.
Help with formalizing the module dependencies would be appreciated.
On a debian-like distro, typically it is sufficient to have the following
extra modules installed on top of a standard php 7 installation:
* Web server with PHP and URL rewrite (such as Apache with mod-rewrite)
* Any version of MariaDB, or MySQL 5 or newer
* php (currently v7)
* php-fpm (also needs to be enabled)
* php-cli
* php-gd
* php-mbstring
* php-mysql
* php-xml
On a Debian-like system, the following command should be sufficient:
# apt install apache2 mysql-server php libapache2-mod-php php-mysql php-xml
# a2enmod rewrite
You may need to turn off the STRICT_TRANS_TABLES sql mode to avoid query errors.
In a sql shell, do
> SET GLOBAL sql_mode = REPLACE(@@GLOBAL.SQL_MODE, 'STRICT_TRANS_TABLES', '');
* FIXME: apparently this is not needed in some cases. Find the root cause.
== Installation and configuration ==
Extract the tarball or clone the VCS to your filesystem:
git clone https://git.savannah.gnu.org/git/h-source.git
You have to create the MySQL database used by h-source. The tables of the database that have to be created are written inside the file tables.sql and distros.sql. A way to carry out this operation is the following:
Open a terminal and type:
# cp Config/Config.php{.sample,}
# cp admin/Config/Config.php{.sample,}
And if necessary:
# cp .htaccess{.sample,}
Now edit those configuration files, at least, defining the DB password 'PWD' under "/*db parameters*/" section in Config/Config.php.
The following constants are mandatory:
* DB // name of the database (the database we will create now)
* USER // database user
* PWD // database password
* HOST // hostname of the mysql server (usually localhost)
* DOMAIN_NAME // domain name of the website (use 'localhost'
or create a virtual host in your web server)
Note that the <USERNAME>, <PASSWORD>, and <DB> in the commands below, must correspond to the "/*db parameters*/" in Config/Config.php and admin/Config/Config.php.
Back at the terminal, type:
# mysql -u <USERNAME> -p
where <USERNAME> is the database user. Write the password and type the following command:
> create database <DB>;
where <DB> is the database name you want to use. Close Mysql by typing the following command:
> exit
Now you have to move inside the folder that contains the tables.sql file and type the following commands:
# mysql -u <USERNAME> -p<PASSWORD> <DB> < tables.sql
# mysql -u <USERNAME> -p<PASSWORD> <DB> < distros.sql
# mysql -u <USERNAME> -p<PASSWORD> <DB> < admin/tables.sql
Now you have created the database named <DB> and populated it with the default accepted/recognized distros. This will also create the default web user having the following credentials:
username: admin
password: admin
Make sure you change the password of this user!
* FIXME: apparently, this is not created sometimes.
> CREATE USER '<USERNAME>'@'localhost' IDENTIFIED BY '<PASSWORD>';
> GRANT ALL ON <DB>.* TO '<USERNAME>'@'localhost' IDENTIFIED BY '<PASSWORD>' WITH GRANT OPTION;
> FLUSH PRIVILEGES;
Create an apache virtual host conf pointing to the h-source directory (say it's /var/www/h-source), enable it and reload the apache web server. Here's a simple example of the Apache virtual host conf:
<VirtualHost *:80>
ServerName <DOMAIN_NAME>
DocumentRoot /var/www/h-source
<Directory /var/www/h-source>
Options Indexes FollowSymLinks MultiViews
AllowOverride All
Order allow,deny
allow from all
</Directory>
ErrorLog ${APACHE_LOG_DIR}/error.log
</VirtualHost>
Direct your browser to the following URL:
http://<DOMAIN_NAME>/
where DOMAIN_NAME is the domain name you have previously set (eg: localhost). You should see the home page of the h-source software.
You will be able to login to the website using the 'admin' user and change the website preferences and the admin password.
== Account issues ==
If you want that the system can send e-mails you have to specify the name of the SMTP server that has to be used. Copy the file Application/Include/params.php.sample to Application/Include/params.php and set the following static attributes of the Website class:
$mailServer = ""; // set the mail server (if $useSMTP = true)
$generalMail = ""; // set the username of your mail account (always needed)
$mailPassword = ""; // set the password of your mail account (if $useSMTP = true)
$fromEmail = ""; // this is the "from address e-mail" used inside the mails
sent by h-source (example: confirmation requesta e-mail,
change password e-mail, ...)
$useSMTP = true; // if you want to use a SMTP account. It can be true or false.
Set $useSMTP to false if you want that the software rely on
the mail() PHP function.
You can also set these constants:
$generalName = ""; // the string that you want to use inside the <title> tag of your website
$projectName = ""; // the name of your project
To configure for the admin app, do the same for admin/Application/Include/params.php.sample.
== Configure the HTML template (right column, top notices, top menu, etc.) ==
Modify the file config.xml inside the ROOT folder of your h-source installation.
If you want to change the position of the config.xml file change the following static attribute of the Website class inside the Application/Include/params.php file:
static public $xmlConfigFileFolder = ROOT; // the constant ROOT contains the
path to the root folder of your
h-source installaton
== Change the homepage ==
Modify the PHP files inside the folder Application/Views/Home
== Change the hardware ==
Modify the PHP file Application/Include/hardware.php
== Change the allowed distributions ==
Modify the PHP file Application/Include/distributions.php
== Change the allowed languages ==
Modify the PHP file Application/Include/languages.php
== How to fill the vendors table ==
After the installation, you have to fill the MySQL table containing the USB/PCI vendors IDs. Note this corresponds to vendors for the USB/PCI interface, which are different from say the notebook vendors which are stored in Application/Include/hardware.php.
To carry out this task, use the scripts in the scripts sub-directory.
Change into the scripts/vendorid/ directory. Copy the file connect.php.sample to connect.php and set the following variables with the same values as your h-node instance:
$host = '<DOMAIN_NAME>';
$user = '<USERNAME>';
$password = '<PASSWORD>';
$dbName = '<DB>';
You will find two files containing the list of vendors: pci.ids and usb.ids. If you want more up-to-date versions of those files then delete them and write the following commands (or download those files from the URLs indicated below):
wget pciids.sourceforge.net/v2.2/pci.ids -O pci.ids
wget http://www.linux-usb.org/usb.ids -O usb.ids
Be sure you have installed php-cli, then write the following command:
php insert_vendors.php
It will fill the 'vendors' MySql table.
== Learn the EasyGiant PHP framework ==
Since h-source is an application of the EasyGiant PHP framework you can use the EasyGiant features in order to modify the h-source source code. Visit www.easygiant.org (archived at http://web.archive.org/web/20161027164429/http://www.easygiant.org/).
You may find a guide to EasyGiant at http://www.easygiant.org/media/guide/20150326.pdf (archived at http://web.archive.org/web/20161027162658/http://www.easygiant.org/media/guide/20150326.pdf).
<!-- NOTE: this file is legal mediawiki syntax -->
<!-- LICENSE
h-source, a web software to build a community of people that want to share their hardware information.
Copyright (C) 2010 Antonio Gallo (h-source-copyright.txt)
Copyright (C) 2022 bill-auger <h-source-users@nongnu.org>
This file is part of h-source
h-source is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
h-source 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 General Public License for more details.
You should have received a copy of the GNU General Public License
along with h-source. If not, see <http://www.gnu.org/licenses/>.
-->
