CHARP Project Setup - pupitetris/charp GitHub Wiki
These are the steps to start development on a CHARP project from scratch. The guide will take you through the making of an example project to illustrate every step of the setup process. Example items will be written between parenthesis. Many indications here should be taken as suggestions on how to organize the files of a project, but you will probably have a diverging opinion.
CHARP projects have been designed to allow development workstations and production and test servers to have as many projects as they can hold, side by side. This means that every project must be identified by a set of names that will be used to discriminate each other's environments at the different levels of the stack, so you will have to choose the following:
- Project name - this will be used at the interface level, for example for the title of new windows and so on (we will call our example project Nacho Libre!).
- Filesystem name - this name will be used to hold all of your project resources and could be used as a prefix for tarballs or packages you may create in the future and stuff like that. Filesystem names shouldn't contain characters that require escaping on the shell and make things difficult to read in shell commands (I personally like CamelCase notation for organizing directories, so we'll use NachoLibre as our example file system name).
- Lowercase name - since PostgreSQL treats all SQL commands and identifiers in case-insensitive mode, to keep things clear we have opted to use UPPERCASE for SQL reserved words and lowercase for identifiers. This name should also be useful for places where the use of uppercase characters is discouraged, such as in hostnames usernames, SCM directories and so on. The best candidate for a lowercase name is a no-caps version of your filesystem name (nacholibre in our case).
- Shell environment prefix - A small set of shell environment variables will have to be declared for the project's setup. Choose the first word of your project as a prefix or if that is not brief enough, try with an abbreviation (in our case, we'll use the prefix NACHO).
- Coding prefix - We will be defining PostgreSQL Stored Procedures, CSS classes and IDs and JavaScript functions which may grow quite a bit in name to describe their purpose, so a minimal prefix to distinguish these entities from others in the system should be a good idea (we will use nl as our function prefix).
First, create a directory where you will hold all of your project resources (use the filesystem name). This directory will hold your code base which you will probably want to keep in a source control repository, and it will also hold other resources that are related to your project but that do not belong to the code base and for which version control is not relevant (for the purpose of our example, we'll be creating it under the home directory):
$ mkdir $HOME/NachoLibre $ cd $HOME/NachoLibre
Now you have to get a copy of the CHARP code base. This will be the base for your own CHARP project and you will code your routines and store your resources inside this directory structure (use the lowercase name for this). Check the Directory and File Structure section for more information on the purpose of the basic files and directories.
We are working on isolating the CHARP source code as much as possible from your own coding so that upgrades on the CHARP infrastructure affect your code as little as possible and to reduce manual editting and merging to a minimum. Most of our efforts have to go on the SQL directory.
To get a copy of the CHARP project, you can do a Git clone of our source repository or download a snapshot (usually the most recent) from our gitweb interface:
$ git clone git://git.berlios.de/charp $ cp -a charp nacholibre $ rm -rf nacholibre/.git
or using wget as a web client to download a snapshot from gitweb (please use your browser to navigate the gitweb and check the URL for the latest snapshot):
$ wget 'http://git.berlios.de/cgi-bin/gitweb.cgi?p=charp;a=snapshot;h=0b0857aa375db3b68e8a838d02d8ac176d7c8f44;sf=tgz' \ -O charp.tgz $ tar xzvf charp.tgz $ cp -a charp-* nacholibre
It is a good idea to keep the original CHARP code base in case you may want to eventually upgrade your own CHARP code to the latest version. This will help to easily generate a patch for the procedure.
For the initialization scripts to work, your shell environment has to be configured. Add the following code to your $HOME/.bash_profile for your own project (sorry, we are assuming you are using bash):
export NACHODIR="$HOME/NachoLibre/nacholibre"
When the SQL scripts run, they will take the connection paramaters from the first four variables. In the example, we are taking the PG* variables as values assuming that such variables already exist in our imaginary environment for our example, inheriting then the default PostgreSQL environment for those values. We want the database to be specific for the project (and not the default) since the initialization script DROPs the database when it runs, and running the initialization script is a very common operation during development.
NACHODIR specifies the location of your personal Nacho Libre installation so project scripts know where to find their resources.
Now save and source your bash_profile from the shell prompt:
$ source $HOME/.bash_profile
This operation will take place automatically with every new shell login that you execute.
If you chose a database user that doesn't exist yet, you have to edit your $HOME/.pgpass to provide a password for the new user. The user will be created by the init.sh script automatically. For example, if we were tu use "nacho" as our user, we should add the line:
*:*:*:nacho:**my password**
to $HOME/.pgpass. If you are creating a new pgpass file, set permissions to 600 (chmod 600 $HOME/.pgpass).
From within your code base directory, edit conf/config.sh and set the PREFIX variable to your shell environment prefix (NACHO in our case). If you are using Power Architect to model your database, uncomment and redefine SQL_EXPORT to as comfortable a location as possible.
Follow the directions inside the file to configure DB_LOCALE, DB_LOCALE_WIN and PGBINDIR.
In scripts/initdb.sh, edit the BASEDIR definition line and set the value to your <PREFIX>DIR varialbe ($NACHODIR in our case). Do the same for scripts/diff.sh.
An Apache virtual host has to be set up.
First, edit your /etc/hosts and make up a name for your virtual host and make it point to your loopback device (in our case we will use our lowercase name and set www.nacholibre.local):
127.0.0.1 www.nacholibre.local
Caveat: Cygwin under certain circumstances won't be able to serve on 127.0.0.1, so try a different IP address, such as the one from your ethernet or WiFi NIC.
The hosts file on Windows can be found on C:\Windows\System32\drivers\etc\hosts, but it may be easier under Cygwin by editing /etc/hosts which points to the aftermentioned file.
If you haven't done so, you'll need a FastCGI module activated on your Apache2 server. mod_fcgid (not to be confused with mod_fastcgi) is recommended because of its profesional configuration flexibility, and it is on active development. After installing, to activate mod_fcgid, use the following command as a superuser:
$ a2enmod fcgid
For the virtual host, copy conf/devel/apache2/conf.d/charp.conf to your Apache2 configuration directory using the lowercase name of your project for the filename:
$ cp conf/devel/apache2/conf.d/charp.conf /etc/apache2/conf.d/nacholibre.conf
The destination directory may vary from distribution to distribution.
Now edit the new virtual host configuration file and replace /var/myproject with the absolute path of your code base directory and replace www.myproject.local with the host name you made up (here we use sed to accomplish this):
$ sed "s/myproject/nacholibre/;s#/var#$HOME/NachoLibre#" /etc/apache2/conf.d/nacholibre.conf > /tmp/aaa $ mv /tmp/aaa /etc/apache2/conf.d/nacholibre.conf
Restart Apache. If the configuration is right, there shouldn't be any errors:
$ /usr/sbin/apache2ctl restart
We have to remove all references to CHARP/myproject so that the database can be initialized and we can do a final test.
Edit site/cgi/CHARP.pm and change the values of the DB_* variables in accordance to your configuration:
$DB_NAME = 'nacholibre'; $DB_HOST = 'localhost'; $DB_PORT = '5432'; $DB_USER = 'nacho'; $DB_PASS = '**my password**';
Rename the Power Architect file, if you are going to use it:
$ mv design/charp.architect design/nacholibre.architect
Open the architect file with a text editor and replace the value of the <project-name> node from CHARP to your file system name (NachoLibre), and then globally change myproject to your lowercase name (nacholibre).
If everything went fine, we can check and see if everything is working (make sure your pg_hba.conf file is in working order):
Initialize the database.
$ ./scripts/initdb.sh DROP DATABASE NOTICE: database "nacholibre" does not exist, skipping DROP DATABASE CREATE DATABASE You are now connected to database "nacholibre". SET CREATE FUNCTION CREATE FUNCTION CREATE DOMAIN ... $
Enter the test site with your web browser (http://www.nacholibre.local/app.html)
If everything went well, you can now do an initial import of the code base directory into your source control system and start developing your new application.