Welcome to Provide!
This project is partitioned into project administration, software club, application services, software development, and requirements management.
Project Administration
Project administration is currently limited to the administration of the project members and application services.
Software Club
Club Host
- Appropriate Software Foundation
Mailing List
Please join the Provide mailing list.
Website
http://appropriatesoftware.net/provide
Application Services
Various deployments to support providing Develop and ScanBooker application services.
Deploying Provide
The Provide system supports the work of providing software application services.
To deploy Provide on a new machine, you will need to:
- Choose a system user for your Provide deployment
- Set the umask and group
- Setup your database user, and database access permissions
- Download the Provide installer
- Install the Provide system
Afterwards, you will want to:
- Acquire and run Provide scripts
- Include Apache server configuration fragments
- Check Mod_python interpreter directives
- Restart the Apache server
Choose System User
Choose which system user account you will use to administer your Provide deployment.
For common web server configurations, we recommend you create a new 'provide' unix user, and then allow for dual-access in the case where the web server will run as a different user (say www-data).
# adduser provide Enter new UNIX password: Retype new UNIX password: Is the information correct? [y/N] y
It is also recommended to avoid the need to dual-access by administering your Provide deployment with the same user as the web server. One possibility is to establish a reverse proxy, and run the rear server as your provide system user.
Set the Umask and Group
Login as the provide user.
# login provide Password:
If you will run the web server as a different system user from your 'provide' user, you will need to allow for "dual access".
To support "dual access", firstly add the web server user to your group.
# addgroup www-data provide
You may also need to change the umask value. The group needs to be able to read and write.
$ umask 0002
Do set this value in your configuration so it works next time you login.
$ vi ~/.bashrc
Just make sure there is a line like this in your .bashrc file.
umask 0002
Setup the Database User and Access Permissions
With Debian and PostgreSQL, change to the system root user, then change to the system postgres user.
Then, if necessary, create the database user for your Provide deployment.
Remember the database password for your database user. You will use it when running the Provide installer (below).
# su postgres $ createuser mydbuser -P Enter password for new role: Enter it again: Shall the new role be a superuser? (y/n) y CREATE ROLE
Answer the questions:
Enter 'y' if you are asked whether the user can create new databases.
Enter 'n' if you are asked whether the user can create new users.
Then, edit the access control configuration. Be careful to edit the correct file for your system:
$ exit exit # vi /etc/postgresql/8.1/main/pg_hba.conf
Just check you have something like this.
# IPv4 local connections: host all all 127.0.0.1/32 md5
If not, add a line like this towards the top of that file.
host all mydbuser 127.0.0.1/32 md5
If you change the config, you will (probably) need to restart the database server.
# /etc/init.d/postgresql-8.1 restart Restarting PostgreSQL 8.1 database server: main.
Whatever you do, make sure you can do things like this.
$ createdb random-dbname -U mydbuser -h localhost
Password for user mydbuser:
CREATE DATABASE
$ psql random-dbname -U mydbuser -h localhost
Password for user mydbuser:
Welcome to psql 8.1.11, the PostgreSQL interactive terminal.
Type: \copyright for distribution terms
\h for help with SQL commands
\? for help with psql commands
\g or terminate with semicolon to execute query
\q to quit
random-dbname=# \q
$ dropdb random-dbname -U mydbuser -h localhost
DROP DATABASE
You need to be able (via TCP/IP sockets) to create databases with any (unused) name, to access and drop such created databases. At least, that's what provide will need to do for you.
Setuptools Version Check
SQLObject needs >= setuptools-0.6c8. So please make sure you've got it installed now!
$ python -c "import setuptools; print setuptools.__version__" 0.6c3
Check which is the latest version ( http://pypi.python.org/pypi/setuptools) then run easy_install.
$ sudo easy_install setuptools==0.6c9
Download the Provide Installer
When the umask is alright, and the database user and access has been setup and tested, the next step is to use the Provide installer to download and install the Provide system.
Download the installer (a shell script), and make it executable.
$ wget -O provide-provide-0.6 http://appropriatesoftware.net/provide/docs/provide-provide-0.6 $ chmod u+x provide-provide-0.6
Run the Provide Installer
The Provide installer takes several optional arguments.
$ ./provide-provide-0.6 --help
usage: provide-provide-0.6 [options]
options:
-h, --help show this help message and exit
-p HOME, --path=HOME path to existing folder (like ~ for example)
-m DOMAINNAME, --domain=DOMAINNAME
name of domain that will be served by provide
-s SECRET, --secret=SECRET
long random string, for security protocols
-b DATABASE, --database=DATABASE
name of database to be created and used by provide
-u USERNAME, --username=USERNAME
name of already existing database user
-w PASSWORD, --password=PASSWORD
password of already existing database user
-v, --verbose run the installation verbosely
-q, --quiet run the installation silently
Now run the installer with your database username and password, the domain you will be providing for and some secret string you invent.
$ ./provide-provide-0.6 --username=dbuser --password=dbpass --domain=provide.mydomain.com --secret=mysecretrandomstring
The installer will firstly check your system for things Provide needs. Required software includes:
- Django 0.96 - latest stable
If the installer reports it can't find a program or a Python model, just install something suitable and then restart the installer.
When your system checks out, the installer will then download and deploy Provide. Depending on your database user configuration, you may need to enter database password when prompted.
If things go wrong after installation has begun, just remove the 'provide-0.6' database if you got that far (check the database name in the provide.conf configuration file), and then remove the '~/.provide/0.6' directory that was created by the installer (location depends on the installer arguments you used).
If things go well, the installer will have printed out a few environment variables to be set when using this Provide deployment.
Provide installed OK. Thanks for using Provide.
Please paste these variables in your environment configuration:
...
Set Environment
If the installation is successful, set the environment variables in your current shell environment, and crucially in your user's environment configuration file so everything still works next time you login.
$ vi ~/.bashrc
Just make sure there are lines like this in your .bashrc file (if you didn't install to your home director you must adjust these paths for your Provide deployment).
$ export PROVIDE_SETTINGS=~/.provide/0.6/etc/provide.conf $ export PYTHONPATH=~/.provide/0.6/lib/python $ export PATH=~/.provide/0.6/bin:$PATH
Check the provide command is now available. Run the following command.
$ which provide
If the 'provide' command is not available, 'which' will return silently and you should check your environment and installation, or seek assistance on the mailing list.
When the installation is successful and your environment is set, the 'which' command will return the full path to the 'provide' command.
$ provide help
Get help on a specific command.
$ provide help scripts
Acquire and Install Provide Scripts
If the 'provide' command is available, you may acquire and install release deployment scripts.
For instance, in the case of ScanBooker version X.Y, you can run this command.
Find the current stable version on the ScanBooker download page.
$ provide scripts scanbooker X.Y
You can then initialise the ScanBooker provision....
$ provide-scanbooker-init
Initialise the ScanBooker X.Y release....
$ provide-scanbooker-X.Y-init
Test the ScanBooker X.Y release....
$ provide-scanbooker-X.Y-accept
Deploy the ScanBooker X.Y release for production....
$ provide-scanbooker-X.Y-production
Remove the ScanBooker X.Y release....
$ provide-scanbooker-X.Y-remove
Remove the ScanBooker provision, and start all over again!
$ provide-scanbooker-remove
Please note: When running Provide scripts, if things don't work out, please join the user mailing list and seek help by reporting accurately what you were trying to do, what you did, and what went wrong.
If things do work out, you will see this message every time.
All provide steps completed OK. Provide script duration: 00h 00m 00s
Full ScanBooker Deployment Instructions
There is more information about deploying ScanBooker on the ScanBooker wiki.
Include Apache Configuration Fragments
Please make sure to include the "purpose" Apache configuration file fragments in the main Apache server configuration file(s).
For the ScanBooker provision (deployed with test, acceptance and production purposes) you will want to add these lines to your Apache server configuration.
If you are distinguishing application services by domain name, just include the vitual server configuration files that Provide creates for each provision purpose.
# Multi virtual host config for provisions distinguished by domain. Include /home/provide/.provide/0.6/var/provisions/scanbooker/purposes/test/etc/httpd.conf Include /home/provide/.provide/0.6/var/provisions/scanbooker/purposes/accept/etc/httpd.conf Include /home/provide/.provide/0.6/var/provisions/scanbooker/purposes/production/etc/httpd.conf
If you are distinguishing application services by path prefix, include the simple configuration file fragments that Provide creates for each provision purpose.
# Single virtual host config for provisions distinguished by path.
NameVirtualHost *
<VirtualHost *>
ServerName violet.appropriatesoftware.net
PythonInterpPerDirective On
Include /home/provide/.provide/0.6/var/provisions/scanbooker/purposes/test/etc/httpd.conf
Include /home/provide/.provide/0.6/var/provisions/scanbooker/purposes/accept/etc/httpd.conf
Include /home/provide/.provide/0.6/var/provisions/scanbooker/purposes/production/etc/httpd.conf
</VirtualHost>
Please note: The paths (above) assume you have deployed Provide to the home directory ('~') of the 'provide' system user.
Check Mod_python Interpreter Directives
Please note: If you are distinguishing your Provide services by path prefix rather than by virtual server name, then you will probably need to set mod_python's PythonInterpPerDirective. See the Mod_python manual for more information.
Please note: This directive is broken in some older versions of Mod_python, so check your version is a good one!
Restart the Apache Server
Before newly created application services will be served, you will probably need to restart your Apache server.
$ sudo apache2ctl restart
And because of database connections, you will also need to restart your Apache server before removing application services which have actually received requests.
Future versions of Provide will support restarting the Apache server at the appropriate moments.
Software Development
Software development tackles the user stories that result from requirements management, and releases updates for the application services.
Free, Agile, Patterns
Provide is being released under the GPL. The project follows an incremental, iterative approach. The project follows the patterns of enterprise application architecture.
Latest Release
The latest release is Provide 0.6.
Development Version
The development version of provide is 0.7.
Just encountered some issues deploying on a fresh Etch:
- formencode was installed with Provide, but not available to ScanBooker?. Need to make sure provide's path isn't available in environment used to install ScanBooker?.
- scanbooker's log file was writable only by provide, not available to www-data even though umask was 0022. Check this out.
- need to have one VirtualHostName? * in the apache config. So have one master apache config file for provide which includes the purpose's fragments, and don't write that directive anywhere. Add an instruction to include the master config file in the main apache config file, and to make sure there's a VirtualHostName? * directive above it in that file.
Mailing List
Developers may join the developer mailing list.
Developers are also encouraged to join the user mailing list.
Subversion Repository
You can browse the svn repository directly in a web browser (but it's better to browse with Trac), or better still point your SVN client at this location and checkout the code.
