Various cleanups and improvements, INSTALL-DEV instructions

14 files changed, 299 insertions, 81 deletions

diff --git a/INSTALL-DEV b/INSTALL-DEV
new file mode 100644
index 0000000..eb5676b
--- /dev/null
+++ b/INSTALL-DEV
@@ -0,0 +1,71 @@
+1. Create PostgreSQL User and Database
+
+$ sudo su postgres
+$ psql
+
+Replace <user> with your login and "www-data" with the user under which
+apache2 is running.
+
+CREATE DATABASE brep;
+CREATE USER <user>;
+GRANT ALL PRIVILEGES ON DATABASE brep TO <user>;
+CREATE USER "www-data" INHERIT IN ROLE <user>;
+
+Make sure the logins work:
+
+$ psql -d brep
+$ sudo sudo -u www-data psql -d brep
+
+To troubleshooting, see logs:
+
+$ sudo tail -f /var/log/postgresql/*.log
+
+
+2. Create Database Schema and Load the Data
+
+All the commands are executed from brep project root.
+
+$ psql --quiet -d brep -f brep/package.sql
+$ loader/brep-loader tests/loader/r.conf # Or some other loader config.
+
+To verify:
+
+$ psql -d brep -c 'SELECT name, summary FROM repository'
+
+
+3. Setup Apache2 Module
+
+Here we assume apache2 is installed and you have an appropriate VirtualServer
+ready (the one for the default site is usually a good candidate). Open the
+corresponding apache2 .conf file and add the following inside VirtualServer,
+replacing <BREP-OUT-ROOT> and <BREP-SRC-ROOT> with the actual absolute paths
+(if you built brep in the source tree, then the two would be the same).
+
+        # brep module configuration.
+        #
+        LoadModule brep_module <BREP-OUT-ROOT>/brep/mod_brep.so
+        SetHandler brep
+
+        brep-conf <BREP-SRC-ROOT>/etc/brep.conf
+
+        # brep static content (CSS files).
+        #
+        # Note: trailing slashes are important!
+        #
+        Alias /pkg/@/ <BREP-SRC-ROOT>/www/
+
+        <Directory "<BREP-SRC-ROOT>/www">
+            Require all granted
+        </Directory>
+
+You may want to replace <BREP-SRC-ROOT>/etc/brep.conf with a custom
+configuration file if you often need to modify it.
+
+Restart apache2 (use the second version for systemd):
+
+$ sudo /etc/init.d/apache2 restart
+$ sudo systemctl restart apache2
+
+To verify, visit the repository root. To troubleshooting, see logs:
+
+$ sudo tail -f /var/log/apache2/error.log
diff --git a/brep/module b/brep/module
index 4ac6023..80a0a56 100644
--- a/brep/module
+++ b/brep/module
@@ -81,7 +81,7 @@ namespace brep
     //
     // While uint8 is more than enough, use uint16 for the ease of printing.
     //
-    uint16_t verb_ {0};
+    uint16_t verb_ = 0;
 
     template <class F> void level1 (const F& f) const {if (verb_ >= 1) f ();}
     template <class F> void level2 (const F& f) const {if (verb_ >= 2) f ();}
diff --git a/brep/module.cxx b/brep/module.cxx
index 253d807..d3ffcb4 100644
--- a/brep/module.cxx
+++ b/brep/module.cxx
@@ -207,7 +207,7 @@ namespace brep
       name_value_scanner s (mo);
       options::module o (s, unknown_mode::fail, unknown_mode::fail);
 
-      verb_ = o.log_verbosity ();
+      verb_ = o.verbosity ();
       loaded_ = true;
     }
     catch (const server_error& e)
diff --git a/brep/options.cli b/brep/options.cli
index d5041c8..aaf0092 100644
--- a/brep/options.cli
+++ b/brep/options.cli
@@ -16,43 +16,107 @@ namespace brep
     //
     class module
     {
-      uint16_t log-verbosity;
-      dir_path root = "/";
+      dir_path root = "/"
+      {
+        "<path>"
+        "Repository root. That is, this is the part of the URL from the host
+         name and until the start of the repository. For example, root value
+         '\cb{/pkg/}' means the repository URL is http://example.org/pkg/.
+         Specify '\cb{/}' to use the web server root (http://example.org/)."
+      }
+
+      uint16_t verbosity = 0
+      {
+        "<level>",
+        "Trace verbosity level. Level 0 disables tracing, which is also the
+         default."
+      }
     };
 
     class db
     {
-      string db-host = "localhost";
-      uint16_t db-port = 5432;
+      string db-user
+      {
+        "<user>",
+        "Database user name. If not specified, then operating system (login)
+         name is used."
+      }
+
+      string db-password
+      {
+        "<pass>",
+        "Database password. If not specified, then login without password is
+         expected to work."
+      }
+
+      string db-name = "brep"
+      {
+        "<name>",
+        "Database name. If not specified, then '\cb{brep}' is used by default."
+      }
+
+      string db-host
+      {
+        "<host>",
+        "Database host name, address, or socket. If not specified, then connect
+         to \cb{localhost} using the operating system-default mechanism
+         (Unix-domain socket, etc)."
+      }
+
+      uint16_t db-port = 0
+      {
+        "<port>",
+        "Database port number. If not specified, the default port is used."
+      }
     };
 
     class search
     {
-      uint16_t search-results = 10;
-      uint16_t pager-pages = 5;
+      uint16_t search-results = 10
+      {
+        "<num>",
+        "Number of results per page. The default is 10."
+      }
+
+      uint16_t search-pages = 5
+      {
+        "<num>",
+        "Number of pages in navigation (pager). The default is 5."
+      }
     };
 
     class package
     {
-      uint16_t description-len = 500; // ~ 80 chars x 6 lines.
-      uint16_t changes-len = 5000; // ~ 80 chars x 60 lines.
+      uint16_t package-description = 500
+      {
+        "<len>",
+        "Number of package description characters to display in brief pages.
+         The default is 500 (~ 80 characters * 6 lines)."
+      }
+
+      uint16_t package-changes = 5000;
+      {
+        "<len>",
+        "Number of package changes characters to display in brief pages. The
+         default is 5000 (~ 80 chars x 60 lines)."
+      }
     };
 
     // Module options.
     //
-    class package_search: module, db, search
+    class package_search: search, db, module
     {
     };
 
-    class package_details: module, db, search, package
+    class package_details: package, search, db, module
     {
     };
 
-    class package_version_details: module, db, package
+    class package_version_details: package, db, module
     {
     };
 
-    class repository_details: module, db
+    class repository_details: db, module
     {
     };
 
diff --git a/brep/package-details.cxx b/brep/package-details.cxx
index 30e185e..a10f668 100644
--- a/brep/package-details.cxx
+++ b/brep/package-details.cxx
@@ -37,7 +37,7 @@ init (scanner& s)
   if (options_->root ().empty ())
     options_->root (dir_path ("/"));
 
-  db_ = shared_database (options_->db_host (), options_->db_port ());
+  db_ = shared_database (*options_);
 }
 
 template <typename T>
@@ -160,7 +160,7 @@ handle (request& rq, response& rs)
     if (const auto& d = pkg->description)
       s << (full
             ? P_DESCRIPTION (*d, id)
-            : P_DESCRIPTION (*d, options_->description_len (),
+            : P_DESCRIPTION (*d, options_->package_description (),
                              url (!full, squery, page, id)));
 
     s << TABLE(CLASS="proplist", ID="package")
@@ -232,7 +232,7 @@ handle (request& rq, response& rs)
 
   t.commit ();
 
-  s <<       DIV_PAGER (page, pkg_count, res_page, options_->pager_pages (),
+  s <<       DIV_PAGER (page, pkg_count, res_page, options_->search_pages (),
                         url (full, squery))
     <<     ~DIV
     <<   ~BODY
diff --git a/brep/package-search.cxx b/brep/package-search.cxx
index 62b162b..448a915 100644
--- a/brep/package-search.cxx
+++ b/brep/package-search.cxx
@@ -37,7 +37,7 @@ init (scanner& s)
   if (options_->root ().empty ())
     options_->root (dir_path ("/"));
 
-  db_ = shared_database (options_->db_host (), options_->db_port ());
+  db_ = shared_database (*options_);
 }
 
 template <typename T>
@@ -138,7 +138,7 @@ handle (request& rq, response& rs)
 
   t.commit ();
 
-  s <<       DIV_PAGER (page, pkg_count, res_page, options_->pager_pages (),
+  s <<       DIV_PAGER (page, pkg_count, res_page, options_->search_pages (),
                         root.string () + squery_param)
     <<     ~DIV
     <<   ~BODY
diff --git a/brep/package-version-details.cxx b/brep/package-version-details.cxx
index 8f6cd7d..9bc06f6 100644
--- a/brep/package-version-details.cxx
+++ b/brep/package-version-details.cxx
@@ -40,7 +40,7 @@ init (scanner& s)
   if (options_->root ().empty ())
     options_->root (dir_path ("/"));
 
-  db_ = shared_database (options_->db_host (), options_->db_port ());
+  db_ = shared_database (*options_);
 }
 
 bool brep::package_version_details::
@@ -152,7 +152,7 @@ handle (request& rq, response& rs)
   if (const auto& d = pkg->description)
     s << (full
           ? P_DESCRIPTION (*d, id)
-          : P_DESCRIPTION (*d, options_->description_len (),
+          : P_DESCRIPTION (*d, options_->package_description (),
                            url (!full, id)));
 
   assert (pkg->location);
@@ -302,7 +302,9 @@ handle (request& rq, response& rs)
     s << H3 << "Changes" << ~H3
       << (full
           ? PRE_CHANGES (ch)
-          : PRE_CHANGES (ch, options_->changes_len (), url (!full, "changes")));
+          : PRE_CHANGES (ch,
+                         options_->package_changes (),
+                         url (!full, "changes")));
 
   s <<     ~DIV
     <<   ~BODY
diff --git a/brep/repository-details.cxx b/brep/repository-details.cxx
index ee34dc2..0d71ac8 100644
--- a/brep/repository-details.cxx
+++ b/brep/repository-details.cxx
@@ -36,7 +36,7 @@ init (scanner& s)
   if (options_->root ().empty ())
     options_->root (dir_path ("/"));
 
-  db_ = shared_database (options_->db_host (), options_->db_port ());
+  db_ = shared_database (*options_);
 }
 
 bool brep::repository_details::
diff --git a/brep/shared-database b/brep/shared-database
index 4d8186d..b445cc1 100644
--- a/brep/shared-database
+++ b/brep/shared-database
@@ -9,6 +9,8 @@
 
 #include <brep/types>
 
+#include <brep/options>
+
 namespace brep
 {
   // Returns pointer to the shared database instance, creating one on the
@@ -17,7 +19,7 @@ namespace brep
   // otherwise. Is not thread-safe.
   //
   shared_ptr<odb::core::database>
-  shared_database (const string& host, unsigned int port);
+  shared_database (const options::db&);
 }
 
 #endif // BREP_SHARED_DATABASE
diff --git a/brep/shared-database.cxx b/brep/shared-database.cxx
index db6b811..1389dab 100644
--- a/brep/shared-database.cxx
+++ b/brep/shared-database.cxx
@@ -14,7 +14,7 @@
 namespace brep
 {
   shared_ptr<odb::database>
-  shared_database (const string& h, unsigned int p)
+  shared_database (const options::db& o)
   {
     using odb::pgsql::database;
     static weak_ptr<database> db;
@@ -25,14 +25,22 @@ namespace brep
     //
     if (shared_ptr<database> d = db.lock ())
     {
-      if (h != d->host () || p != d->port ())
+      if (o.db_user ()     != d->user ()     ||
+          o.db_password () != d->password () ||
+          o.db_name ()     != d->db ()       ||
+          o.db_host ()     != d->host ()     ||
+          o.db_port ()     != d->port ())
         throw std::runtime_error ("shared database host/port mismatch");
 
       return d;
     }
     else
     {
-      d = make_shared<database> ("", "", "brep", h, p);
+      d = make_shared<database> (o.db_user (),
+                                 o.db_password (),
+                                 o.db_name (),
+                                 o.db_host (),
+                                 o.db_port ());
       db = d;
       return d;
     }
diff --git a/etc/brep-apache2.conf b/etc/brep-apache2.conf
new file mode 100644
index 0000000..6f806e8
--- /dev/null
+++ b/etc/brep-apache2.conf
@@ -0,0 +1,49 @@
+# The brep.conf file can be included once into Apache configuration file in
+# the <VirtualHost> section or in the main server context.
+#
+LoadModule brep_module modules/mod_brep.so
+LoadModule alias_module modules/mod_alias.so
+
+# Alternatively, if loading the modules in another place, make sure they
+# are loaded.
+#
+<IfModule !brep_module>
+  Error "mod_brep is not loaded"
+</IfModule>
+
+<IfModule !alias_module>
+  Error "mod_alias is not loaded"
+</IfModule>  
+
+# To use a repository root other than /pkg/, replace all occurrences of
+# /pkg/ with the desired alternative root (use '/' for webserver root).
+#
+brep-root            /pkg/
+brep-db-host         localhost
+brep-db-port         5432
+brep-search-results  10
+brep-pager-pages     5
+brep-description-len 500
+brep-changes-len     5000
+brep-log-verbosity   0
+
+# To override brep module options place them into the separate configuration
+# file, suppressing the "brep-" prefix.
+#
+#brep-conf /path/to/brep-site.conf
+
+SetHandler brep
+
+# Location of the brep static content (CSS files).
+#
+Alias /pkg/@/ /usr/share/brep/static/
+
+<Directory "/usr/share/brep/static">
+  Require all granted
+</Directory>
+
+# Serve repository files from the repository root path. For example:
+#
+#   http://example.org/pkg/1/...  -> /path/to/repo/1/...
+#
+#AliasMatch ^/pkg/(\d+)/(.+) /path/to/repo/$1/$2
diff --git a/etc/brep.conf b/etc/brep.conf
index 6f806e8..05981be 100644
--- a/etc/brep.conf
+++ b/etc/brep.conf
@@ -1,49 +1,45 @@
-# The brep.conf file can be included once into Apache configuration file in
-# the <VirtualHost> section or in the main server context.
+# Configuration file for the brep module (note: this is not an apache2 .conf
+# file). See brep(1) for detailed description of each configuration option.
+# Commented out options indicate their default values.
 #
-LoadModule brep_module modules/mod_brep.so
-LoadModule alias_module modules/mod_alias.so
 
-# Alternatively, if loading the modules in another place, make sure they
-# are loaded.
+# Repository root. Use '/' (default) for web server root.
 #
-<IfModule !brep_module>
-  Error "mod_brep is not loaded"
-</IfModule>
+root /pkg/
 
-<IfModule !alias_module>
-  Error "mod_alias is not loaded"
-</IfModule>  
 
-# To use a repository root other than /pkg/, replace all occurrences of
-# /pkg/ with the desired alternative root (use '/' for webserver root).
+# Number of results per page.
 #
-brep-root            /pkg/
-brep-db-host         localhost
-brep-db-port         5432
-brep-search-results  10
-brep-pager-pages     5
-brep-description-len 500
-brep-changes-len     5000
-brep-log-verbosity   0
+# search-results 10
 
-# To override brep module options place them into the separate configuration
-# file, suppressing the "brep-" prefix.
+
+# Number of pages in navigation (pager).
+#
+# search-pages   5
+
+
+# Number of package description characters to display in brief pages.
 #
-#brep-conf /path/to/brep-site.conf
+# package-description 500
 
-SetHandler brep
 
-# Location of the brep static content (CSS files).
+# Number of package changes characters to display in brief pages.
 #
-Alias /pkg/@/ /usr/share/brep/static/
+# package-changes     5000
 
-<Directory "/usr/share/brep/static">
-  Require all granted
-</Directory>
 
-# Serve repository files from the repository root path. For example:
+# Database connection configuration. By default, brep will try to connect to
+# the local instance of PostgreSQL with the operating system-default mechanism
+# (Unix-domain socket, etc) and use operating system (login) user name and the
+# database called 'brep'. See brep(1) for details.
 #
-#   http://example.org/pkg/1/...  -> /path/to/repo/1/...
+# db-user
+# db-password
+# db-name      brep
+# db-host
+# db-port
+
+
+# Trace verbosity. Disabled by default.
 #
-#AliasMatch ^/pkg/(\d+)/(.+) /path/to/repo/$1/$2
+# verbosity 1
diff --git a/loader/loader.cxx b/loader/loader.cxx
index 7d8570a..4512b8d 100644
--- a/loader/loader.cxx
+++ b/loader/loader.cxx
@@ -38,13 +38,13 @@ using namespace brep;
 namespace pgsql = odb::pgsql;
 
 static void
-usage ()
+usage (ostream& os)
 {
-  cout << "Usage: brep-loader [options] <file>" << endl
-       << "File lists internal repositories." << endl
-       << "Options:" << endl;
+  os << "Usage: brep-loader [options] <file>" << endl
+     << "File lists internal repositories." << endl
+     << "Options:" << endl;
 
-  options::print_usage (cout);
+  options::print_usage (os);
 }
 
 static inline bool
@@ -715,25 +715,29 @@ main (int argc, char* argv[])
     //
     if (ops.help ())
     {
-      usage ();
+      usage (cout);
       return 0;
     }
 
     if (argc < 2)
     {
-      cout << "<file> argument not provided" << endl;
-      usage ();
+      cerr << "<file> argument not provided" << endl;
+      usage (cerr);
       return 1;
     }
 
     if (argc > 2)
     {
-      cout << "unexpected argument encountered" << endl;
-      usage ();
+      cerr << "unexpected argument encountered" << endl;
+      usage (cerr);
       return 1;
     }
 
-    pgsql::database db ("", "", "brep", ops.db_host (), ops.db_port ());
+    pgsql::database db (ops.db_user (),
+                        ops.db_password (),
+                        ops.db_name (),
+                        ops.db_host (),
+                        ops.db_port ());
 
     // Prevent several loader instances from updating DB simultaneously.
     //
@@ -825,7 +829,7 @@ main (int argc, char* argv[])
   catch (const cli::exception& e)
   {
     cerr << e << endl;
-    usage ();
+    usage (cerr);
     return 1;
   }
   // Fully qualified to avoid ambiguity with odb exception.
diff --git a/loader/options.cli b/loader/options.cli
index 7045a22..e46a548 100644
--- a/loader/options.cli
+++ b/loader/options.cli
@@ -8,19 +8,41 @@ namespace brep
 {
   class options
   {
-    bool --help {"Print usage information and exit."};
-    bool --version {"Print version and exit."};
+    bool --help {"Print usage information and exit."}
+    bool --version {"Print version and exit."}
 
-    string --db-host = "localhost"
+    string --db-user|-u
+    {
+      "<user>",
+      "Database user name. If not specified, then operating system (login)
+       name is used."
+    }
+
+    string --db-password
+    {
+      "<pass>",
+      "Database password. If not specified, then login without password is
+       expected to work."
+    }
+
+    string --db-name|-n = "brep"
+    {
+      "<name>",
+      "Database name. If not specified, then '\cb{brep}' is used by default."
+    }
+
+    string --db-host|-h
     {
       "<host>",
-      "Connect database server using specified host or socket directory."
-    };
+      "Database host name, address, or socket. If not specified, then connect
+       to \cb{localhost} using the operating system-default mechanism
+       (Unix-domain socket, etc)."
+    }
 
-    uint16_t --db-port = 5432
+    uint16_t --db-port|-p = 0
     {
       "<port>",
-      "Connect database server using specified port."
-    };
+      "Database port number. If not specified, the default port is used."
+    }
   };
 }