<chapter id="ch-create-new-project">
    <title>Creating a New Project</title>

    <para>This section addresses using the APLAWS build tools to create a new
    project, or instance of your project. This may be for development or for
    use as a staging server. </para>
    <note><title>Note:</title>
<para>This section assumes that you have all the necessary tools
installed for a working development area. The steps for setting up a
development environment is beyond the scope of this document. Please
consult the installation guide for details.</para></note> 

<sect1 id="s1-quick-steps-setup">
  <title>Quick Guide for the Impatient</title>
  <orderedlist>
    <listitem>
      <para>As the root user, create a system login for the
development user (<xref linkend="s1-setup-users"/>).</para>
    </listitem>
    <listitem>
      <para>As the root user, set up the new development user as for
the development
      environment with the command <command>ccm-devel-user.sh</command> <replaceable>username</replaceable> (<xref linkend="s2-setup-devel-user"/>)</para>
    </listitem>
    <listitem>
      <para>As the development user, start a new APLAWS project with
the command <command>ccm-devel-create.pl</command> <option>--extends
aplaws aplaws_</option><replaceable>xxx</replaceable> (<xref
linkend="s1-create-project"/>)</para>
    </listitem>
    <listitem>
      <para>
        Familiarize yourself with the web directory, the dev
directory, and CVS (<xref linkend="s2-project-directory"/>, <xref
linkend="s2-web-directory"/>, <xref
linkend="s2-shared-source-directory"/>, and <xref
linkend="s2-create-project-cvs"/>).
      </para>
    </listitem>
  </orderedlist>
  
  
</sect1>

    <sect1 id="s1-setup-users">
        <title>Setting up Users</title>

        <para>This section should be carried out by the system
administrator. The first step is to create accounts for all users who
will be
        developing with APLAWS. This has two steps:</para>

        <orderedlist>
            <listitem>
                <para>Create a system login</para>
              </listitem>

            <listitem>
                <para>Create a &CCM; development area</para>
              </listitem>
        </orderedlist>

        <note>
            <title>Note</title>

            <para>A user only has to be setup once. Once their system account
            and &CCM; development environment have been created, they can create
            any number of projects without having to go through this process
            again.</para>
        </note>
        
        <sect2 id="s2-create-system-login">
            <title>Creating a system login</title>

            <para>The following commands will create a new user,
            set the password for that user and add the user to the
            <command>ccm-devel</command> group.</para>

<screen>
<command>useradd</command> <option>-m</option> <replaceable>username</replaceable>
<command>passwd</command> <replaceable>username</replaceable>
<command>gpasswd</command> <option>-a</option> <replaceable>username</replaceable> <option>ccm-devel</option>
</screen>

            <note>
                <title>Note</title>
                <para>These commands are for &RHELAS;. These will be slightly
                different on other systems, but the effect must be the
                same.</para>
            </note>
        </sect2>

        <sect2 id="s2-setup-devel-user">
            <title>Set Up the Development User with the Development Environment</title>

            <para>Once a user is created, you need to configure the  &CCM; development
            area for them. This is done with the
            <command>ccm-devel-user.sh</command> command, which must be executed
            as <command>root</command>.</para>
<screen>
<command>ccm-devel-user.sh</command> <replaceable>username</replaceable>
</screen>
        </sect2>
    </sect1>

    <sect1 id="s1-create-project">
        <title>Starting a new APLAWS project</title>

        <para>Login as the development user that was just created for you.  To
start a new project, based on APLAWS we use the
        <option>--extends</option>. For the project name a good naming scheme
        would be to concatenate the word aplaws_ with your organization name, e.g.
        <command>aplaws_herefordshire</command>. Putting those two bits together, we
        get:</para>


<screen>
<prompt>bash-2.05b$</prompt> <command>ccm-devel-create.pl</command> <option>--extends aplaws aplaws_</option><replaceable>xxx</replaceable>

<computeroutput>
Installation complete; your server will run on port 9005.
</computeroutput>
</screen>

        <para>You should make a note of this port number. When you have your
        instance running, you will access it at the URL
        http://<replaceable>your-server</replaceable>:<replaceable>port</replaceable>/.
        <note><title>Note:</title>
<para>The port number of your development server can also be
found in the configuration file for your servlet container. This is
located in
        <filename>/var/ccm-devel/web/<replaceable>username</replaceable>/<replaceable>projectname</replaceable>/conf.</filename>
      </para>
</note>

<note>
  <title>Troubleshooting</title>
  <para>
    If you make a mistake running this command, you can undo the
    effects by removing the web and dev directories it created. You
will need to <command>rm -rf </command> the following directories:
<itemizedlist> <listitem>
  <para>
    <filename>/var/ccm-devel/dev/<replaceable><optional>username</optional></replaceable>
    /<replaceable>projectname</replaceable>
  </filename>
  </para>
</listitem>
<listitem>
  <para><filename>/var/ccm-devel/web/<replaceable>username</replaceable>/<replaceable>projectname</replaceable></filename></para>
</listitem>
</itemizedlist>
  
  </para>
</note>
</para>

<para>
  The <command>ccm-devel-create.pl</command> command creates two
directories for your use. The <emphasis>project web</emphasis> directory and
the <emphasis>project dev</emphasis> directory. From this point on, the project dev directory will be refered to as the <emphasis>dev directory</emphasis>.
It is important that you do
not confuse the two directories,the web directory is for your web
server and should not be modified directly. The
<emphasis>project</emphasis> on the other hand is your dedicated working
area. Since your project will be based on APLAWS also important to
note the function of the <emphasis>shared source</emphasis> directory
where the APLAWS code lives.
</para>

<sect2 id="s2-project-directory">
  <title>Dev Directory</title> 

<para>The dev directory is located at
  <filename>/var/ccm-devel/dev/<replaceable>username</replaceable>/<replaceable>projectname</replaceable></filename>. This
is the directory that will contain all your custom code. When you use
ant to deploy your code, the Java, jsp, and XSL in this directory will
be compiled and placed in the appropriate locations in the web
  directory. The contents of this directory is discussed in more detail in the  <xref linkend="s1-project-directory"/> section.</para>

</sect2>
<sect2 id="s2-web-directory">
  <title>Web Directory</title>
  <para> The web directory is located at
  <filename>/var/ccm-devel/web/<replaceable>username</replaceable>/<replaceable>projectname</replaceable></filename>. This
area is dedicated to your application server. All content in this
directory except for the <filename>conf</filename> subdirectory,
should be reproducible from the contents of the dev directory and the
shared source directories.  You should <emphasis>never</emphasis> make
changes directly in this directory.  </para> 
</sect2> 

<sect2 id="s2-shared-source-directory">
  <title>Shared Source Directory</title>
  <para>
    The shared source directory is at
<filename>/usr/share/ccm-devel/projects/<replaceable>aplaws-xxx</replaceable></filename>. This
is where the APLAWS code base lives, the files here should not be
modified, and only used as a reference. The code in this directory and
the code in the <emphasis>project</emphasis> directory is complied and
placed in the <emphasis>web directory</emphasis> for use by the web server.
</para> </sect2>



        <sect2 id="s2-create-project-cvs">
            <title>CVS</title>

            <para>If you installed the <command>ccm-devel-cvs</command> package,
            the system will automatically perform some CVS tasks for you.
            Namely:</para>
            
            <itemizedlist>
                <listitem>
                    <para>Create a new CVS module</para>
                  </listitem>

                <listitem>
                    <para>Check out an existing CVS module</para>
                  </listitem>
            </itemizedlist>

            <para>When you create a new project the system will check to see if
            there is already a CVS module by the same name. For example, of you
            created a project called <command>aplaws_camden</command>, it will
            look for a CVS module called
            <command>aplaws_camden</command>.</para>

            <para>Depending on whether or not the CVS module already exists, it
            will create or use it as appropriate.</para>

            <note>
                <title>Note</title>

                <para>This is the only way in which CVS is directly used by the
                build tools. If have a good understanding of CVS and
                have more complicated requirements, it is quite safe to change
                the default setup after it has been created.</para>
            </note>


            <para>
              For further reference on CVS please refer to the <ulink
url="http://www.cvshome.org">CVS manual</ulink>.
          </para>
        </sect2>
      </sect1>
</chapter>











