A quick and dirty C++17 web application (free software, GPLv3+) to help neighbours making essential buying (food, medicine) during the 2019–20 coronavirus pandemic for older neighbours (avoiding elder persons having to go out, improving the necessary confinement, assuming users are well behaved and wantinng to help or needing help).
For Linux/x86-64 only. GCC compiled. On https://github.com/bstarynk/helpcovid/
The web server application runs on Linux (like most web servers). The users are using recent web browsers (Firefox, Chrome, mobile phones) on various computers (perhaps running non-Linux based operating systems, such as Windows, MacOSX, etc...), tablets, mobile phones connected to the World Wide Web.
The helpcovid web server application is extensible thru
plugins. See our
file PLUGINS.md. So site-specific extensions are
possible. In particular because different countries have different
regulations.
covid19md-voluntari-server in Python, from Moldavia. Also work in progress.
Please contact one of the authors by email. See email addresses elsewhere.
If you read French, see also this and the CNIL agency.
Of course that application stores personal data in some PostGreSQL database, so is concerned by GDPR ... It is expected to be used in good faith. HelpCovid accepts plug-ins having a GPLv3+ compatible license, and these are dlopen(3) at startup time.
HelpCovid may be configured to use setuid techniques. Beware that using them incorrectly can ruin the cybersecurity of your entire Linux servers.
If RefPerSys was ready, it should have been used instead.
In France, see also enpremiereligne.fr and covid19-que-lire.fr; look also into covid19-floss-initiatives
Because the main developers know it, and because it should be more efficient than a PHP or Python application (which one of the developers Basile Starynkevitch does not know well). Hopefully, a C++17 code could be more efficient. Scalability is achieved also by using a PostGreSQL database which could run on a different server.
The end-user is expected to have a computer or a mobile phone with a
recent Web browser (e.g. Firefox 68) understanding HTML5 and
JavaScript
(i.e. AJAX and
EcmaScript6 ...) and
with WebSockets and
connected to the Internet. The end-user is supposed to be honest and a
good enough person, and will volunteerly but in good faith add
honestly some personal information about him/her-self (real name,
email, phone number, perhaps even if he/she is in good health). We do
try to code in a defensive way, against some malicious hackers. We
have no time for W3C accessibility
issues
(e.g. usage of helpcovid by blind persons) but accept patches to
improve accessibility.
We hope to add something to help health professionals and food shops (e.g. registering their actual open hours and availability).
We want to use OpenStreetMap, but are not familiar with it.
We want to code a web application which could be deployed in several countries (hopefully one Linux VPS server per city).
Of course GPLv3+
Notice that you take the responsability about personal data and privacy issues when deploying this free software (e.g. GDPR in Europe).
See PLUGINS.md for more. Several plugins are possible, and might provide country or city specific features.
We use a PostGreSQL relational database. See DATABASE.md for more.
Basile Starynkevitch, near
Paris, France; email
basile-freelance@starynkevitch.net - see my web
page and my
resume
for contact details.
Abhishek Chakravarti, near Kolkota, India; email abhishek@taranjali.org
Niklas Rosencrantz, from
Stockholm, Sweden; email niklasro@gmail.com
Captchas photos made by Basile Starynkevitch and resized by Matthieu Starynkevitch.
libpq from PostGreSQL 11 for the database.
libpqxx for C++ frontend to PostGreSQL.
cpp-httplib for C++ HTTPS service.
curlpp, a C++ wrapper around the famous
libcurl, which is an HTTP and HTTPS
client library. Some resources useful for HelpCovid may need to be
downloaded at startup time by ./helpcovid or its plugins.
Websocket++ for WebSockets.
Twitter Bootstrap for the responsive CSS framework.
Start Bootstrap - Blog Home for the Bootstrap theme.
Bootstrap Cookie Alert for the GDPR notice popup.
On Debian (Buster) run:
sudo aptitude install postgresql-server-dev-11 postgresql-client-11 postgresql-11 libpqxx-dev libconfig++-dev libglibmm-2.4-dev libcurlpp-dev
but both
cpp-httplib and Websocket++ need to be built from the source
The ./helpcovid executable accepts both --help and --version
program arguments. It uses environment variables (see
environ(7),
getenv(3) ...)
prefixed with HELPCOVID_. The default configuration file (it is some
Glib key
file...)
is /etc/helpcovid.conf (or given with --config= program argument
or $HELPCOVID_CONFIG environment variable) parsed by
GlibMM with .ini like
syntax in our file hcv_main.cc at startup.
The web root is webroot/ or the $HELPCOVID_WEBROOT environment variable. e. g. export HELPCOVID_WEBROOT=/home/helpcovid/webroot
The served URL is the $HELPCOVID_URL environment variable e.g. export HELPCOVID_URL=https://b-star-y.tech/helpcovid
The PostGreSQL connection URI is the $HELPCOVID_POSTGRESQL environment variable, e.g. export HELPCOVID_POSTGRESQL=postgresql://www-data@localhost/helpcovid_db
The OpenSSL encryption for
HTTPS may use the OpenSSL
certificate provided by $HELPCOVID_SSLCERT and the OpenSSL key
provided by $HELPCOVID_SSLKEY. See also the --websslcert and
--websslkey program options. These files should not be
world-readable.
Customization of HTML contents visible to the end-user happens with
processing
instructions
starting with <?hcv (that triggers dynamic HTML generation) and
ending with ?> on the same line. In particular,
internationalization and
localization
of messages in our HTML files (under webroot/html/) is done by
processing instructions on a single line such as, for example
something as <?hcv msg MAINPAGE_HEADING Page Heading?> handled by
C++ code in hcv_template.cc function hcv_initialize_templates
which should use
locale(7)
facilities such as
gettext(3), and
chunk customization facilities.
In some HTML-like files, template expansion occurs. These are
SGML-like processing
instructions
starting with <?hcv in lower-case. See our source file
hcv_template.cc. For example <?hcv now?> should be expanded into the
current date and time.
HTML files subject to template expansion should have an HTML comment
containing !HelpCoVidDynamic! in the first 8 lines.
The user browser should support HTML5, AJAX, and
WebSockets. The websocket
URL start with /websocket/ and should be secure.
See mostly HTTP_PROTOCOL.md for more.
Edit the Makefile then run make. Run the ./generate-config.py script to
generate the configuration details for the web server and the PostgreSQL server. That ./generate-config.py script knows about the --help option.
Subsequently run make localtest0 to run the test web server, and point your
browser to http://localhost:8089/login (replacing http://localhost:8089 with
the URL you had specified in the ./generate-config.py script).
We use PostGreSQL and we require a PostGreSQL 12 server.
To create the database on Debian, first get Linux root permission (e.g.
with sudo -s). Then, according to
this PostGreSQL tutorial you need to run (as Linux root) the su - postgres command (which gives you access to the "PostGreSQL superuser")
and run under that PostGreSQL user the createdb helpcovid_db command.
Concretely, the steps needed to setup the helpcovid database from psql are as
follows with PostGreSQL password 1234helpcovid is:
$ sudo -u postgres psql
postgres =# CREATE DATABASE helpcovid_db;
postgres =# CREATE USER helpcovid_usr WITH PASSWORD 'passwd1234helpcovid';
postgres =# ALTER ROLE helpcovid_usr SET client_encoding TO 'utf8';
postgres =# ALTER ROLE helpcovid_usr SET default_transaction_isolation TO 'read committed';
postgres =# ALTER ROLE helpcovid_usr SET timezone TO 'UTC';
postgres =# GRANT ALL PRIVILEGES ON DATABASE helpcovid_db TO helpcovid_usr;
postgres =# \q Notice that to destroy entirely the database, we would use DROP DATABASE helpcovid_db;.
When running helpcovid, the database password may sit in your
$HOME/.pgpass
file. This file may
need to be set to have 0600 permissions.
The $HOME/.pgpass file would contain a single line similar to the following:
localhost:5432:helpcovid_db:helpcovid_usr:However, there is a possible caveat to consider -- that the $HOME/.pgpass file
might be applicable to the psql program, and not to the libpqxx library. In
such a case, we could still benefit from having a password file (other than
$HOME/.pgpass) that contains the following connection string:
dbname=helpcovid_db user=helpcovid_usr password=passwd1234helpcovid \
hostaddr=localhost port=5432Read more about PostGreSQL connection
string. Notice
that the password could be kept in a file given with passfile.
This connection string (excluding the backslash) would be read by the
hcv_initialize_database() function and used in the constructor for
pqxx::Connection.
To change passwords in PostGreSQL see this.
A mandatory configuration file should be provided, by the --config
program argument, or by the $HELPCOVID_CONFIG environment variable,
or in $HOME/helpcovid.conf or in the /etc/helpcovid.conf system
configuration file.
That configuration file is a Glib key-value
file
and cannot be world-readable. It is read by the hcv_load_config_file
C++ function and can be accessed by C++ functions
hcv_config_has_group, hcv_config_has_key, hcv_config_do.
helpcovid groupIt provides "global" settings. See our C++ function
hcv_config_handle_helpcovid_config_group.
log_message, a string giving some log message.
seteuid, to use dangerous
seteuid facilities. Never
use them without first reviewing our hcv_main.cc source file,
because there could be a huge cybersecurity risk.
startup_popen_command, a dangerous string passed to
popen(3)
which is run once at startup. Use with great caution, and review our
code in hcv_main.cc before using it. The output of that pipe goes
to the system log. It is run after seteuid facilities.
html_email_popen_command, a command
popen(3)-ed
to send HTML5 emails. Invoked as command subject
destination-email ... and getting the HTML5 body as standard
output.
pid_file, a file path where the process id of the running helpcovid
process is written. Defaults to
/var/run/helpcovid.pid. Overridable by $HELPCOVID_PIDFILE or
--write-pid option.
threads, the number of working threads. Overridable by $HELPCOVID_NBWORKERTHREADS or
--threads option.
locale, for localization, see
locale(7),
setlocale(3),
dggettext(3). Overridable
by $HELPCOVID_LOCALE or --locale option. See C++ functions
hcv_view_expand_msg in file hcv_views.cc and hcv_get_locale in
file hcv_main.cc ...
custom_messages_file for customized messages organized in one or
several chunkfiles. See also
CUSTOMIZATION.md. That file path is tilde- and
dollar- expanded (like shells do,
e.g. globbing)
to several files using
wordexp(3)
(see also
glob(7)...).
These chunk files should have a name ending with a letter or digit.
web groupIt can provide the following keys (for cpp-httplib ...):
url for the served URL basename, e.g. http://localhost:8089; same role as $HELPCOVID_WEBURL environment variable or --web-url program option.
root for the served HTTP root document directory, e.g. /var/www/helpcovid/; same role as $HELPCOVID_WEBROOT environment variable or --webroot program option.
sslcert for the OpenSSL certificate (used for HTTPS) e.g. /etc/helpcovid/sslcert.pem; same role as $HELPCOVID_SSLCERT or --websslcert
sslkey for the OpenSSL private key (used for HTTPS) e.g. /etc/helpcovid/sslkey.pem; same role as $HELPCOVID_SSLKEY or --websslkey
postgresql groupIt can provide the following keys (for libpqxx that is to PostGreSQL:
connection, the connection string for
pcxx::connection; same role
as $HELPCOVID_POSTGRESQL or --postgresl-databaseThe logo for the application can be changed by replacing the default
helpcovid-logo.svg icon found in the webroot/images directory.
First, run once and successfully the generate-config.py.
If something goes wrong, you may need to restore PostGreSQL to a pristine state with:
sudo -u postgres psql
DROP DATABASE helpcovid_db;
DROP USER helpcovid_usr;
\qand one of the DROP above could be not needed.
The run make localtest0
After that, use your browser, e.g. on http://localhost:8089/ if that was the URL you configured for helpcovid
See C++ class Hcv_email_template_data implemented in C++ file hcv_template.cc and configuration html_email_popen_command in group [helpcovid].
See C++ functions hcv_database_with_known_email, hcv_user_model_find_by_email, etc...
The emails are sent in HTML5 format and customized by files under emailtempl/ directory.
We use the HelpCovid software group on https://web.whatsapp.com/
The phone number of Basile Starynkevitch there is +33 6 8501 2359
helpcovid@framalistes.orgSee https://framalistes.org/sympa/info/helpcovid
Please follow the following conventions and stay civil and nice. The forum website is overloaded, so don't work quickly. Expect a few hours of delay between sending a message there and seeing it thru the web interface.
all emails are in English and public
an email related to medical questions (e.g. should we ask our users about their body temperature) should have a subject starting with MEDICAL:
an email about privacy issues (e.g. GDPR concerns) should start with PRIVACY:
an email about database (e.g. what SQL request is best) should have a subject starting with DATABASE:
an email about software development (e.g. how to compile libpqxx) should start with DEVEL:
an email about software deployment (e.g. how to start the executable) should start with DEPLOY:
any other topic should start with a lowercase letter
Some of the hyperlinks are in French, sorry.
For a few requests, https://geo.api.gouv.fr/adresse for example https://api-adresse.data.gouv.fr/search/?q=92340
which actually gives a JSON with all streets in Bourg La Reine
????
http://download.geonames.org/export/zip/
We suppose honest adult and responsible users. Given Covid 19 urgency (in France, see the Décret n° 2020-260 du 16 mars 2020 by French prime minister for example) we are supposing GDPR compliance, even if this software collects personal data.... (which is relevant for deployment not for coding). We don't have time to check for that compliance.
First, one would voluntarily register himself/herself, with first name, last name, birth year or approximate age (e.g. I am between 50 and 55 years old), email, phone, home-address and optionally possibly more health related information.
Then a user would -on his/her free will- add more information about himself/herself. We dream of providing an infrastructure where someone could on his free will declare:
I am health professional
I am a fragile person (pregnant, sick, aged above 65 years, etc...)
I am willing to do some shopping for close neighbour
I need some neighbour help to get me food
etc...
And we optimistically hope to provide a list of close neighbours (closer than 2km, so at a walking distance) willing to help.
in French
Nous supposons des utilisateurs adultes, honnêtes et responsables. Compte tenu de l'urgence (en France, voir le Décret n° 2020-260 du 16 mars 2020 du Premier ministre etc...) nous supposons -sans en être sûr- être conforme à la RGPD même si bien sûr ce logiciel collecte des données personnelles (c'est pertinent au déploiement, pas au codage). Nous n'avons pas le temps de vérifier cette conformité.
En premier lieu, un utilisateur s'enregistrerait de son plein gré avec ses prénoms, nom de famille, année de naissance (ou tranche d'âge), lieu de résidence, et peut-être même des informations liées à sa santé.
Puis cet utilisateur ajouterait -de sa propre volonté- des informations supplémentaires. Nous rêvons de fournir une infrastructure permettant d'indiquer:
je suis un professionnel de santé
je suis fragile (car enceinte, malade, agé de plus de 65 ans, etc...)
je suis volontaire pour faire des courses pour de proches voisins
je cherche un voisin pour faire des courses (alimentaires) pour moi.
etc...
Et nous espérons pouvoir fournir une liste de proches voisins (à moins de 2 km) désireux d'aider.
See HTTP_PROTOCOL.md
We provide the software, not the data.
See DEPLOYMENT.md
Once you run make you might try something like ./helpcovid -W http://192.168.0.1:8083/ -R $PWD/webroot/ -T 3 -D for debugging
purposes (where 192.168.0.1 is an IPv4 address of your Linux computer, as
reported by ip addr -see
ip(8)- or
ifconfig(8)
Linux commands). Then from a browser (maybe your mobile phone) access
http://192.168.0.1:8083/ or http://192.168.0.1:8083/status.json
We use the address
sanitizer. See the
Makefile and build with make sanitized-helpcovid.
You can also do make localtest0; see the Makefile
In March 2020 ./helpcovid is often crashing.
If your system's /etc/hosts file contains a line 0.0.0.0 anyhost
you could try to run ./helpcovid -W http://anyhost:8089/ -R $PWD/webroot/ -T 2 -D but then beware if your computer is connected
to the Internet with some open ports: your helpcovid process would
then be accessible from outside.
To generate self-signed HTTPS certificates for our --websslcert= and
--websslkey program options, see
this.