[Maintain-dev] The revised file
Edward Lim
limed at onid.orst.edu
Wed Jan 31 13:30:15 PST 2007
Here is the revised file
Ed
-------------- next part --------------
--------------------------------------------------------------------------
--------- Maintain -- INSTALL ---------
--------------------------------------------------------------------------
$Id$
--------------------------------------------------------------------------
Installing Maintain:
This document is intended to get you up and running with Maintain.
It is also available on the Maintain website, along with more docu-
mentation and some web links to make your necessary system adjustments
as easy as possible.
-------------------------------------------------------------------------------
0. Understanding Maintain:
For information on what Maintain is designed to do, it's highly
recommended that you read README.design in the documentation directory
or on the Maintain website before installing to get an idea of the
high-level design of Maintain and how to best leverage it in your
environment.
Another valuable resource is the whole Maintain community website,
available under:
http://maintainproject.osuosl.org/
-------------------------------------------------------------------------------
1. Required Components:
Maintain was developed with the following software versions.
This list does not imply that Maintain won't work under any circumstances
with software versions less than the ones mentioned. However, running
Maintain on up-to-date software versions is strongly recommended, and
older versions than the ones written here are not supported.
Base:
Apache >= 1.3.29 http://www.apache.org [1]
PHP >= 4.3 http://www.php.net [2]
MySQL >= 4.1 http://www.mysql.com [3]
PHP-LDAP >= 4.1.2 http://www.php.net
Perl >= 5.6.1 http://www.perl.com [4]
PHPHTMLLib >= 2.5.4 http://phphtmllib.newsblob.com/ [5]
DNS:
djbdns >= 1.05 http://cr.yp.to/djbdns.html
DHCP:
ICS dhcpd >= 3.0 http://www.isc.org/sw/dhcp/
Notes:
[1] Maintain needs a web server capable of executing PHP scripts. But since
no special abilities of Apache are used, it should also run on any other
UNIX web server. Please let us know of your success when running it on
different setups. (You can add something to the user forums on the Maintain
website.)
For security reasons, We recommend use of Apache-ssl or mod_ssl with Apache
rather than just plain Apache.
[2] Currently, Maintain is not compatible with PHP5.
[3] Maintain was mostly developed on MySQL 4.1, however it also runs on
MySQL 5. If you experience any bugs with new versions of MySQL, please let
us know.
[4] Since version 3.0, Maintain is fully written in PHP4. However, there
are small, optional features that require Perl when activated. If you
want to use them, please make sure you have installed Perl on your Maintain
box. (When Perl is required, it is mentioned in the respective config file)
[5] If you have PHPHTMLLib installed, you can link Maintain to your current
version. If not, there are Maintain downloads available that contain a copy
of PHPHTMLLib for your convenience.
-------------------------------------------------------------------------------
2. Set up your servers.
2.1 Base System and DHCP/DNS Server Environments
Maintain is intended to run on GNU/Linux servers. Any flavor/distribution
should be alright. Even other Unixes (like BSD) might work, but are
currently unsupported.
Please make sure that the software versions mentioned above are installed
on your server(s). For your convenience, we recommend installing the
software packages with the package management system provided by your
Linux distribution (e.g. apt-get, yum, portage etc.).
The server which Maintain should run on is supposed to have all the tools
running that are mentioned under "Base" above. Generally spoken, this is
a regular "LAMP" (Linux, Apache, MySQL, PHP) system.
Please have a dedicated (empty) MySQL database up and running and a MySQL
user that has full write access to this database. You will need to enter
the connection data into the config files later.
It is recommended to call the database used by Maintain 'maintain'.
If the default database name is used, configuration will be easier later.
The DHCP and DNS servers are supposed to have the respective server
packages running. If you do not need DHCP, for example, you obviously do
not have to provide that server either. You just won't enable it in
Maintain.
2.2 PHP Settings
Some components in Maintain can use more memory than PHP's default memory
limit. In case the scripts hit the limit, they will break.
Therefore, Maintain requires at least a 16 MB memory limit to function
properly.
To do so, become root and edit the file php.ini, which is usually in the
directory /etc (or /etc/php4 or similar).
Search for the line:
memory_limit = 8M ; Maximum amount of memory a script may consume
and change it to:
memory_limit = 16M ; Maximum amount of memory a script may consume
It is also recommended that you verify that the magic_quotes_gpc option
is turned off. Though having this option on will not hurt Maintain, it
can lead to forms populating values with excessesive slashes in them to
the screen.
Search for the line:
magic_quotes_gpc = On
If you choose to deactive this option you will only need to change the
the word On to Off like so:
magic_quotes_gpc = Off
Save the file and restart your webserver (Apache) afterwards.
Note: Some linux distributions have two php.ini files, one for the web
interface and another one for the command line interface.
In this case, change the setting in both of them.
-------------------------------------------------------------------------------
3. Getting Maintain
There are several ways to get an instance of Maintain. We highly recommend
to install a Maintain release, however there are also nightly SVN snapshots
and a subversion checkout available.
If you just extracted Maintain and are reading this file in the install
directory, you may go on with step 4.
3.1. Downloading a Maintain Release
This is the recommended way of obtaining Maintain:
Go to the website (maintainproject.osuosl.org), go to the download area
and fetch the newest release version of Maintain.
3.2. Downloading a Nightly Snapshot
On the Maintain website, there are also nightly snapshots of the develop-
ment tree available.
You may download and extract them just as described in section 3.1 for
the official releases.
It is not recommended to run nightly snapshots on production systems.
Nightly builds may break at any time or do other unintended things and
should therefore only be used for development purposes.
3.3. Using the SVN tree
Maintain is developed in a Subversion revision control environment.
You can download, play around with, and modify the whole Maintain source
code.
However, we strongly discourage using SVN snapshots in a production
environment.
Even "worse" than nightly snapshots, SVN checkouts may break at any time,
do strange things to your system and/or database, or arbitrarily invite
a family of manatees to a dinner party at your house.
Therefore, the SVN process is only described in the Maintain hacking
documentation.
For more information on hacking Maintain, read the HACKING document in
the documentation and/or visit the Maintain website.
-------------------------------------------------------------------------------
4. Installing Maintain
Go to the desired directory where you want to install Maintain.
Note that it is STRONGLY discouraged to have Maintain lying in your
webserver directory (typically /var/www or similar), since people might
be able to read important config files otherwise.
Instead, extract it to a folder that is READABLE by the web server user
(typically "apache" or "www-data"), but not writable. A good installation
directory is for example:
/data/maintain or
/opt/maintain
Then extract the file:
tar xvzf maintain-$version.tar.gz (for the tar.gz release) or:
tar xvjf maintain-$version.tar.bz2 (for the tar.bz2 release)
Afterwards, make the $maintain/htdocs directory available for your web
server. There are at least two ways to do this:
1) Symbolic link
Go into your web server root directory (typically /var/www or similar)
and make a symbolic link to your Maintain htdocs directory:
ln -s /opt/maintain/htdocs maintain
You want to make sure that the option "FollowSymlinks" is set for your
web server directory, otherwise you will not be able to access the link
you just created.
2) Virtual Host
You may also set up a virtual host pointing to the htdocs directory, so
that your instance of Maintain can be reached by accessing
http://maintain.example.com
or similar. Setting up virtual hosts is beyond the scope of this document,
but for Apache, this is a good place to start:
http://httpd.apache.org/docs/2.0/vhosts/
-------------------------------------------------------------------------------
5. Setting Up Maintain
Now it is time to set up Maintain. You have to edit a few options in the
main config file before you can run the Maintain installer.
5.0 Descriptions
$prefix == Location where you extracted maintain
$web_path == URL of maintain
5.1 Setting up Config Options
1) Copy $prefix/maintain.cfg.dist to
$prefix/maintain.cfg
2) Edit $prefix/maintain.cfg and configure Maintain.
The least parts you have to edit are:
- the prefix and web_path variables
- the path to your instance of PHPHTMLLib
- the database information
To set a variable as false comment it out with a #.
For the initial setup you must have [Auth] "methods = mysql",
which is the default.
5.2 Creating the Database Link Files
If your (empty) maintain database has the name 'maintain', you can skip
this step.
Otherwise execute the 'create tables' script as follows
cd $prefix
make db
The script creates the database link scripts needed for Maintain to connect
to your database. No error messages should occur.
5.3 Setup Wizard
1) Open a web-browser and go to $web_path, where the Maintain installer
will welcome you.
Please follow the instructions given by the installer script to set up
an initial zone and admin user.
a) The installer will use the mysql connection information you provided
in the config file to prepare the initial Maintain database.
If you skipped step 5.2 but have a database name different than
'maintain', the installer will ask you to run that step now.
b) If you had an older version of Maintain running, the Installer script
will help you to migrate. Please refer to the according documentation
in $prefix/documentation/MIGRATE.
c) The installer will ask you to create an admin password. Keep in mind not
to do the setup unencryptedly over a public network, if possible,
because then your web browser will send the admin password to Maintain
in clear text. Maintain encryptedly stores the password afterwards.
d) At last, you will be asked to make an initial, empty zone to start off
with. For the concept of zones, refer to documentation/README.design.
-------------------------------------------------------------------------------
6. First Network Setup
* See the general use documentation for more information *
1) Go to the Admin section and create a new IP Block for your
IP space. Make sure it's enabled.
2) Create the first subnet within the bound of your IP Block.
Assign any DHCP options to this subnet (router & subnet mask)
3) Create a Master Domain.
4) Edit the zone created during setup and add this new domain
as an allowed domain.
5) Create a new range that fits inside your subnet.
6) Assign this new range to your zone.
You should now be able to create hosts in this zone and assign them to the
new range and domain.
-------------------------------------------------------------------------------
7. Cron Setup
1) This will depend on your system, setup cron to run
$prefix/bin/build/all -p
however often you would like it to build the files. Make sure you edit
$prefix/maintain.cfg
as well as the individual module config files to reflect the build
setup.
2) Set up the build modules to perform the "push" step for you (i.e.
copying the config files to your target servers) or copy them to the
right destination manually.
-------------------------------------------------------------------------------
8. Installing Maintain on a debian based system
1) From the above we know that we need Apache, MySQL, PHP4 for maintain to work
the following is the name of the packages required for a Debian based system
Package:
apache2
php4
php4-mysql
mysql-server-4.1
mysql-client-4.1
mysql-common
libapache2-mod-php4
Optional package:
phpmyadmin
2) All of these packages can be installed using the apt-get command
apt-get install <package name>
3) The rest of the install is the same as the above in the documentation. So you can
refer above for more information on how to setup maintain.
-------------- next part --------------
Coding Standards for Maintain
=============================
Daniel I. Robert <robert at osuosl.org>
1.0, 1 August 2005
[[scope]]
Scope and Purpose
-----------------
In any large, open-source application, coding practices between developers
differ, sometimes wildly. In an effort to keep Maintain consistent, the project
maintainers have put together criteria that they expect outside contributors to
adhere to.
[[who]]
Who Should Read This Document
-----------------------------
All patch submissions, modules, and skins are subject to these guidelines. The
project managers may reject a code submission purely on the basis that it does
not comply with the guidelines laid out in this document. Some existing code
in Maintain may not strictly comply due to legacy reasons, and will likely be
changed in future releases. Consider this a "do as we say and not as we do"
coding standards document.
[[struct]]
Source Tree
-----------
Please consult the documentation regarding the source code layout to guide you
on where your code belongs in the tree and how to properly lay it out. Since
Maintain 3.0, there has been a rigid structure defining the proper layout of
code within the source tree.
[[text]]
Text/Code Format
----------------
Visible in the xref:header[next section] is the typesetting standards used in
the Maintain source tree. *Do not use tabs!* Tabs should be replaced by four
space characters. The relevant vim settings are given below. For more
information on this, please see the
link:http://pear.php.net/manual/en/standards.php#standards.indenting[PEAR
coding standards] page.
[[header]]
Header
------
The following header should be included on all files that are non-trivial.
Documents such as includes or constants definitions do not need such a header
(use of such a header in these documents is, in fact, discouraged).
-------------------------------------------------------------------------------
/* vim: set expandtab tabstop=4 shiftwidth=4 foldmethod=marker: */
// $HeadURL$
// +------------------------------------------------------------------------+
// | Maintain - DNS/DHCP Managment Tool |
// +------------------------------------------------------------------------+
// | Copyright (c) 2005 Open Source University |
// +------------------------------------------------------------------------+
// | This program is free software; you can redistribute it and/or |
// | modify it under the terms of the GNU General Public License |
// | as published by the Free Software Foundation; either version 2 |
// | of the License, or (at your option) any later version. |
// | |
// | This program is distributed in the hope that it will be useful, |
// | but WITHOUT ANY WARRANTY; without even the implied warranty of |
// | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
// | GNU General Public License for more details. |
// | |
// | You should have received a copy of the GNU General Public License |
// | along with this program; if not, write to the Free Software |
// | Foundation, Inc., 59 Temple Place - Suite 330, |
// | Boston, MA 02111-1307, USA. |
// +------------------------------------------------------------------------+
// | Author(s): Foobar Johnson <johnsonf at example.com> |
// +------------------------------------------------------------------------+
// $Id$
-------------------------------------------------------------------------------
[[doc]]
Documentation
-------------
Maintain 3.0 now uses phpDocumentor (phpdoc) for API documentation. All
classes in Maintain are required to use phpdoc for clarity and to assist other
programmers. More information on phpDocumentor can be found
link:http://www.phpdoc.org/[at http://www.phpdoc.org/].
[[phpdoc]]
phpDocumentor Standards
~~~~~~~~~~~~~~~~~~~~~~~
The page-level docblock for a file should look something as follows (for a file
containing nothing more than a class and some requires)
------------------------------------------------------
/**
* filename.php - defines the {@link classname} class
* @author author name or $Author$
* @filesource
*
* @package packagename
* @subpackage subpackagename
*/
------------------------------------------------------
Where 'filename'.php refers to the name of this particular file, and
'classname' is the class defined within it. The rest of this page block is
literal. Even though the doc-block for the class should define its own package
and, optionally, subpackage), the page-level docblock should define it as well.
Users with commit rights should leave the @author value as '$Author$', while
independant contributors are encouraged to enter their own names in there, lest
it be overwritten by the committers name.
[[packages]]
Packages
^^^^^^^^
The Maintain 3.0 API is split into distinct packages and subpackages that
roughtly follow the directory structure. The hierarchy looks something as
follows (all names are strictly lower-cased):
- bin
- build
- classes
* auth
* dao
* htdocs
* ui
- htdocs
* datalists
* forms
- includes
- modules
* subpackage for each module
- skins
* subpackage for each skin
[[nonapi]]
Non-API Documentation
~~~~~~~~~~~~~~~~~~~~~
Non-API documentation (such as this document) are written in the AsciiDoc
format. Maintain has chosen AsciiDoc for its pre-generated readability and
ease of use. Many Linux distros, such as Debian, have Asciidoc packages
available. Any non-phpdoc documentation present in a skin, module, etc.,
should be written in this format if possible, and given a `.txt` extension.
[[code]]
Coding
------
.Format
Maintain strives to comply with
link:http://pear.php.net/manual/en/standards.php[PEAR coding standards].
.Capitalization
Although Maintain 3.0 is a PHP4 application, the code is becoming increasingly
object-oriented. As such, we are using nerdyCaps for long variable, method,
and class names. PHP files containing classes should be cased in the Java
style, i.e. a file containing the class `myClass` should be named `MyClass.php`
.Documentation
The Maintain team does *NOT* believe in the concept of 'self-documenting code'.
Every hacker has written "self-documenting code" only to look back on it a few
weeks later and wonder what on earth they were trying to do. We hope all
incoming code is clean, well indented, and takes advantage of whitespace, but
the Maintain team insists on actual comments (and comment blocks as needed)
throughout the code base. Please do not submit any code that is undocumented.
[[disc]]
Discussion
----------
During working hours, we are typically reachable in IRC on the freenode network
in #maintain . To track svn commits, we have a bot set up in #osuosl-commits
that displays real-time commits for all of the Oregon State's Open Source Lab's
projects. There is a general mailing list of Maintain discussions. Please
sign up at
link:http://lists.osuosl.org/mailman/listinfo/maintain[http://lists.osuosl.org/mailman/listinfo/maintain]
.
More information about the Maintain-dev
mailing list