commit-gnue
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

[gnue] r6983 - in trunk: gnue-appserver gnue-appserver/doc gnue-common/d


From: reinhard
Subject: [gnue] r6983 - in trunk: gnue-appserver gnue-appserver/doc gnue-common/doc
Date: Thu, 10 Feb 2005 07:28:29 -0600 (CST)

Author: reinhard
Date: 2005-02-10 07:28:28 -0600 (Thu, 10 Feb 2005)
New Revision: 6983

Added:
   trunk/gnue-appserver/doc/configuration.txt
   trunk/gnue-common/doc/hints.firebird.txt
   trunk/gnue-common/doc/hints.mysql.txt
   trunk/gnue-common/doc/hints.postgresql.txt
Modified:
   trunk/gnue-appserver/INSTALL
   trunk/gnue-appserver/MANIFEST.in
   trunk/gnue-appserver/setup.py
Log:
Improved installation and configuration docs.


Modified: trunk/gnue-appserver/INSTALL
===================================================================
--- trunk/gnue-appserver/INSTALL        2005-02-09 19:34:27 UTC (rev 6982)
+++ trunk/gnue-appserver/INSTALL        2005-02-10 13:28:28 UTC (rev 6983)
@@ -22,8 +22,8 @@
   - python-mysqldb (for MySQL) [python-mysqldb]
   - KInterbasDB (for Interbase/Firebird) [python-kinterbasdb]
   - PySQLite (for SQLite) [python-sqlite]
-  you can find more information about possible database backends in the file
-  README.Databases, distributed with GNUe Common.
+  You can find more information about possible database backends on the web
+  page http://www.gnuenterprise.org/tools/common/databases/.
 
 * at least one of the following RPC libraries:
   - py-xmlrpc [python-xmlrpc]
@@ -60,112 +60,5 @@
 Configuration
 -------------
 
-(Future releases might have an own documentation file describing configuration
-more detailed)
-
-The most important configuration file for gnue-appserver is "connections.conf".
-If you did a standard installation, you can find it in /usr/local/gnue/etc.
-
-On the machine running gnue-appserver, you must have an entry in the
-connections.conf pointing to your database.  The default database name in
-appserver is "gnue".  You can change it with the command line option
-"--database".  If you don't use postgresql you have to set the username and
-password for the database you want to use by command line options.
-
-Example for a correct connections.conf entry on the machine running
-gnue-appserver:
-
-  [gnue]
-  comment = Database for GNUe Application Server
-  provider = psycopg
-  host = localhost
-  dbname = gnue
-
-On the machine running the front ends (gnue-forms, gnue-reports,
-gnue-designer), you need an entry in the connections.conf that points to the
-Application Server.  If you have the front ends installed on the same machine
-as gnue-appserver, there's only a single connections.conf with both entries.
-
-Example for a correct connections.conf entry on the machine running gnue-forms,
-gnue-reports or gnue-designer:
-
-  [appserver]
-  comment = Connection to the GNUe Application Server
-  provider = appserver
-  rpctype = xmlrpc
-  host = localhost
-  port = 8765
-  transport = http
-
-
-Setting up the database and class repository
---------------------------------------------
-
-Before you can start gnue-appserver, you have to create a database and populate
-it with the class repository.
-
-For PostgreSQL, Interbase/Firebird, MySQL or SQLite:
-* execute the script 'gnue-setupdb'
-
-All other backends:
-* create your database as described in your database documentation
-* make sure you have access to this database and it fits your settings in the
-  connections.conf
-* in the directory '/usr/local/gnue/share/gnue/appserver' run the command
-  "gnue-schema --connection=gnue gnue.gsd"
-  this will create and populate all tables needed for the classrepository
-
-
-NOTE:
-
-If you're using PostgreSQL, Interbase/Firebird or MySQL you have to make sure
-your account has enough privileges to create a new database in order to use
-gnue_setupdb. Please contact your database administrator or consult your
-database documentation for further details.
-
-How to gain privileges (the quick and dirty way)
-
-PostgreSQL:     
-  edit /etc/postgresql/pg_hba.conf and set host, db or user to 'trust'
-  To grant 'trusted' (full) access from the local host add a line like:
-
-    host  all  all  127.0.0.1     255.255.255.255  trust
-
-  To grant 'trusted' (full) acces from the LAN 192.168.32.*
-
-    host  all  all  192.168.32.0  255.255.255.0    trust
-
-
-MySQL:
-  enter the mysql database using the 'mysql' tool and create a privileged
-  account for your user:
-
-    GRANT ALL PRIVILEGES ON *.* TO 'foobar'@'%' IDENTIFIED BY 'fred';
-    GRANT ALL PRIVILEGES ON *.* TO 'foobar'@'localhost' IDENTIFIED BY 'fred';
-
-  (the second grant will be needed for local access). To automate access
-  control add a file "~/.my.cnf" with the following contents:
-
-    [mysqladmin]
-    username = foobar
-    password = fred
-
-    [mysql]
-    username = foobar
-    password = fred
-
-  Please make sure this file has mode 0600 :)
-
-
-Interbase/Firebird:
-
-  In order to create a new database one will need the password of 'SYSDBA'. On
-  creation of a database gnue-schema will prompt for this password
-
-
-Populate the database with sample classes and data
---------------------------------------------------
-
-To set up the database for the samples, make sure that you have created and
-populated the database as described above, and run setup-db.sh from the
-samples directory.
+Please refer to the file "configuration.txt" in the "doc" directory for a
+explanation of the necessary configuration steps.

Modified: trunk/gnue-appserver/MANIFEST.in
===================================================================
--- trunk/gnue-appserver/MANIFEST.in    2005-02-09 19:34:27 UTC (rev 6982)
+++ trunk/gnue-appserver/MANIFEST.in    2005-02-10 13:28:28 UTC (rev 6983)
@@ -8,6 +8,7 @@
 include THANKS
 include TODO
 
+include doc/configuration.txt
 include doc/gcd.dtd
 include doc/gld.dtd
 include doc/api/Makefile

Added: trunk/gnue-appserver/doc/configuration.txt
===================================================================
--- trunk/gnue-appserver/doc/configuration.txt  2005-02-09 19:34:27 UTC (rev 
6982)
+++ trunk/gnue-appserver/doc/configuration.txt  2005-02-10 13:28:28 UTC (rev 
6983)
@@ -0,0 +1,165 @@
+Configuration of the GNU Enterprise Application Server
+======================================================
+
+First thing you have to do is to install the gnue-appserver package and all its
+dependencies.  You have several ways of doing this:
+
+A. Install the packages available for your platform and distribution of choice.
+   * Debian packages are included in the standard distribution.
+   * Ubuntu packages are contained in the "universe" component.
+   * Microsoft Windows installation files in .exe format are available at
+     http://www.gnuenterprise.org/downloads/current.php
+   (If you provide packages for other platforms/distributions please let us
+   know so we can add you to this list)
+
+B. If no ready-made packages are available for your platform and distribution,
+   download the source packages of gnue-common and gnue-appserver from
+   http://www.gnuenterprise.org/downloads/current.php and follow the
+   instructions given in the file "INSTALL" of each of these packages.
+
+C. If you *really* want to follow the bleeding edge of development, you can
+   access our SVN repository by following the instructions given at
+   http://www.gnuenterprise.org/developers/svn.php. Please make sure your read
+   the files "INSTALL.cvs" and "README.cvs" in every package, if available.
+
+Once you have installed the gnue-common and gnue-appserver packages, you have
+to do several configuration steps:
+
+
+1. Prepare your database backend
+--------------------------------
+
+Make sure that your database server is running and accepting connections from
+the machine you want to run gnue-appserver on.  Also make sure that your
+current user is allowed to create new users and new databases on the database
+server.
+
+Please refer primarly to the documentation of your database server about how to
+achieve and test this.  However, the files "hints.postgresql.txt",
+"hints.mysql.txt" and "hints.firebird.txt" in gnue-common's documentation
+directory contain some hints on how to set up the respective database servers
+for use with GNU Enterprise.
+
+Note that you do not yet create the actual database on the database server.
+
+
+2. Set up your connections.conf
+-------------------------------
+
+The most important configuration file for gnue-appserver is "connections.conf".
+On Posix compatible systems (like GNU/Linux) you will find this file in the
+"/etc" directory (for prepackaged versions) or in the "/usr/local/gnue/etc"
+directory (if you installed from the source packages).  Alternatively, all GNU
+Enterprise tools accept a "--connections" paramter that overrides the location
+of the connections.conf file.
+
+On the machine running gnue-appserver, you must have an entry in the
+connections.conf pointing to your database.  The default database name in
+appserver is "gnue".  You can change it with the command line option
+"--database".  If you don't use postgresql you have to set the username and
+password for the database you want to use by command line options.
+
+Example for a correct connections.conf entry on the machine running
+gnue-appserver:
+
+  [gnue]
+  comment = Database for GNUe Application Server
+  provider = psycopg
+  host = localhost
+  dbname = gnue
+  username = frank
+  password = secret
+
+[gnue]: the name of the database connection (you can define several connections
+  to different databases in the same connections.conf file).  You can tell
+  gnue-appserver which connection to use with the "--database" command line
+  parameter or with the "database" configuration option in gnue.conf.
+
+comment: comment text without any special meaning
+
+provider: can for example be "psycopg", "pygresql", or "pypgsql" for PostgreSQL
+  database servers (depending on the database driver you installed), "mysql"
+  for MySQL database server, "interbase" for Firebird/Interbase database
+  servers, or "sqlite" if you use the SQLite embedded database.
+
+host: hostname of the machine running the database server
+
+dbname: name of the database
+
+username: user name gnue-appserver should use to connect to the database.
+  Some databases do not or not always require a username.  If a username is
+  required, you can either define it here or with the "--username" command line
+  parameter to gnue-appserver.  If no username is given, it defaults to "gnue".
+
+password: password gnue-appserver should use to connect to the database.
+  Some databases do not or not always require a password. If a password is
+  required, you can either define it here or with the "--password" command line
+  parameter to gnue-appserver.
+
+You can find more information about the available database drivers (providers)
+and the required and optional entries in connections.conf for each of them on
+http://www.gnuenterprise.org/tools/common/databases/.
+
+
+3. Create the basic database
+----------------------------
+
+Before you can start gnue-appserver, you have to create a database and populate
+it with some system tables.
+
+For PostgreSQL, Firebird/Interbase, MySQL or SQLite:
+* execute the script 'gnue-setupdb'
+
+All other database servers:
+* create your database as described in your database documentation
+* make sure you have access to this database and it fits your settings in your
+  connections.conf
+* in the directory "/usr/share/gnue/appserver" (if you installed a prepackaged
+  version) or "/usr/local/gnue/share/gnue/appserver" (if you installed from the
+  source packages), run the command "gnue-schema --connection=gnue gnue.gsd".
+
+At this point, you should be able to run gnue-appserver.
+
+
+4. Feed applications into the application server
+------------------------------------------------
+
+The GNU Enterprise Application Server defines a directory (or a list of
+directories) to be the "module path".  Applications written for the GNU
+Enterprise Application Server provide files with the ending ".gcd" and ".gld".
+These files have to be copied into that directory (or into one of the
+directories in the list, respectively), or a subdirectory thereof.
+
+The module path can be defined with the "modulepath" configuration option in
+gnue.conf and overridden with the "--modulepath" command line parameter to
+gnue-appserver.  If you wish to specify a list of directories to search
+through, separate the directories by a semicolon (";").
+
+If the module path is neither configured in gnue.conf nor specified on the
+command line, it defaults to "/usr/share/gnue/appserver" for prepackaged
+installs, and to "/usr/local/gnue/share/gnue/appserver" for standard installs
+from the source packages.
+
+Some applications also provide files with an extension of ".gsd" that contain
+default or sample data.  You can read in those files with the command
+"gnue-schema --connection=gnue <filename>".
+
+
+5. Configure access to gnue-appserver for the front end
+-------------------------------------------------------
+
+On the machine running the front ends (gnue-forms, gnue-reports,
+gnue-designer), you need an entry in the connections.conf that points to the
+Application Server.  If you have the front ends installed on the same machine
+as gnue-appserver, there's only a single connections.conf with both entries.
+
+Example for a correct connections.conf entry on the machine running gnue-forms,
+gnue-reports or gnue-designer:
+
+  [appserver]
+  comment = Connection to the GNUe Application Server
+  provider = appserver
+  rpctype = xmlrpc
+  host = localhost
+  port = 8765
+  transport = http

Modified: trunk/gnue-appserver/setup.py
===================================================================
--- trunk/gnue-appserver/setup.py       2005-02-09 19:34:27 UTC (rev 6982)
+++ trunk/gnue-appserver/setup.py       2005-02-10 13:28:28 UTC (rev 6983)
@@ -79,12 +79,11 @@
     wfeimages   = self.allfiles ("extensions/webfrontend/images")
     grpcfiles   = ["grpc/appserver.grpc"]
     man1files   = self.allfiles ("doc/man")
-    docfiles    = ["INSTALL",
+    docfiles    = ["doc/configuration.txt",
                    "doc/gcd.dtd",
                    "doc/gld.dtd",
                    "doc/api/api.txt",
-                   "doc/devguide/devguide.txt",
-                   "doc/whitepaper/whitepaper.txt"]
+                   "doc/devguide/devguide.txt"]
     samplefiles = self.allfiles ("samples")
 
     params ["data_files"] = \
@@ -135,10 +134,6 @@
     if os.system ("cd doc/devguide && make devguide.txt") != 0:
       sys.exit (1)
 
-    print "building documentation: doc/whitepaper"
-    if os.system ("cd doc/whitepaper && make txt") != 0:
-      sys.exit (1)
-
     if action == 'sdist':
       print "building documentation: doc/technotes"
       if os.system ("cd doc/technotes && make") != 0:

Added: trunk/gnue-common/doc/hints.firebird.txt
===================================================================
--- trunk/gnue-common/doc/hints.firebird.txt    2005-02-09 19:34:27 UTC (rev 
6982)
+++ trunk/gnue-common/doc/hints.firebird.txt    2005-02-10 13:28:28 UTC (rev 
6983)
@@ -0,0 +1,15 @@
+Using the Firebird/Interbase database with GNU Enterprise
+=========================================================
+
+
+Setting up the permissions on the database server
+-------------------------------------------------
+
+Firebird/Interbase has a predefined user "SYSDBA" that generally has the
+permission to create new users and databases.
+
+Every time GNU Enterprise tries to create a new user or a new database, the
+SYSDBA password will be asked.
+
+For newly installed databases servers, this password defaults to "masterkey".
+It is certainly a good idea to change that password.

Added: trunk/gnue-common/doc/hints.mysql.txt
===================================================================
--- trunk/gnue-common/doc/hints.mysql.txt       2005-02-09 19:34:27 UTC (rev 
6982)
+++ trunk/gnue-common/doc/hints.mysql.txt       2005-02-10 13:28:28 UTC (rev 
6983)
@@ -0,0 +1,29 @@
+Using the MySQL database with GNU Enterprise
+============================================
+
+
+Setting up the permissions on the database server
+-------------------------------------------------
+
+Enter the mysql database using the 'mysql' tool and create a privileged account
+for your user:
+
+  GRANT ALL PRIVILEGES ON *.* TO '<user>'@'%' IDENTIFIED BY '<pwd>';
+  GRANT ALL PRIVILEGES ON *.* TO '<user>'@'localhost' IDENTIFIED BY '<pwd>';
+
+(replace <user> with your username and <pwd> with your database password)
+(the second grant will be needed for local access)
+
+To automate access control, you can add a file "~/.my.cnf" with the following
+contents:
+
+  [mysqladmin]
+  username = <user>
+  password = <pwd>
+
+  [mysql]
+  username = <user>
+  password = <pwd>
+
+(replace <user> with your username and <pwd> with your database password)
+Please make sure this file has mode 0600 :)

Added: trunk/gnue-common/doc/hints.postgresql.txt
===================================================================
--- trunk/gnue-common/doc/hints.postgresql.txt  2005-02-09 19:34:27 UTC (rev 
6982)
+++ trunk/gnue-common/doc/hints.postgresql.txt  2005-02-10 13:28:28 UTC (rev 
6983)
@@ -0,0 +1,22 @@
+Using the PostgreSQL database with GNU Enterprise
+=========================================================
+
+
+Setting up the permissions on the database server
+-------------------------------------------------
+
+NOTE: This is the quick and dirty way, granting full, passwordless access to a
+given host or subnet.  You most probably don't want this in production
+environments.  Please refer to your PostgreSQL documentation for setting up
+access permissions properly.
+
+For the quick and dirty "full access" configuration, edit the file
+/etc/postgresql/pg_hba.conf and set host, db or user to 'trust'.
+
+To grant 'trusted' (full) access from the local host add a line like:
+
+  host  all  all  127.0.0.1     255.255.255.255  trust
+
+To grant 'trusted' (full) acces from the LAN 192.168.32.*
+
+  host  all  all  192.168.32.0  255.255.255.0    trust





reply via email to

[Prev in Thread] Current Thread [Next in Thread]