Once you have your project setup, you should use the commands from the &CCM; build tools to set up your environment variables and begin development. You should always login as your development user or su - developmentuser, ccm-profile projectname, and cddev. Please see , and . Here is a outline of the steps for starting development the first time. Each step has a reference link to the detailed documentation in the later section. While this will get you started, not all the commands are referenced from this section, you should read through the whole document to familiarize yourself with the command set and take full advantage of the build environment. Log in as the development user Set up your shell environment variables with the command ccm-profile project_name (). cddev to get to the dev directory (). Edit ant.properties and project.xml ( . Generate config.vars with the command ant make-config (, Create server readable configuration file enterprise.init with the command ant make-init (). Deploy the code with ant deploy (). Load the datamodel by going into the web directory and running the apropreate create script (). Start the server with ccm-start, follow the progress with tailllogs (, ). ccm-profile project_name This command sets up the environment variables in your shell. It also makes all other commands available, and customizes them to work with a particular project. Because ccm-profile creates all the other build tool commands, it must be run first. Failing to run ccm-profile will most likely result in the error command not found when trying to execute any other build tool command. Change directory to the current project's development directory. See the section on for an explanation of its contents. Change directory to the current project's web directory. This contains the logs, configuration files and the deployed web application. Changes are not normally made directly in this directory or any of its sub-directories. Rather changes are made automatically by the build tools. Making changes directly in the web directory can cause unpredictable results. The APLAWS server will generate a variety of logs while it is running. The location of the log files are determined by the configuration parameter in config.vars called log-dir. Usually this is set to a subdirectory called logs in the dev directory ( ). The taillogs displays new entries in all log files immediately as they are added. To quit, type CtrlC. The log files displayed are located at /var/ccm-devel/web/username/projectname/logs/. When they grow above a certain size (by default 1MB), log files are rolled, which means the log file is renamed and a new one is created for new entries. If this happens to a file while you are viewing it, you will stop seeing updates. If you suspect this has happened, stop taillogs and restart it. The same as taillogs, except just for /var/ccm-devel/web/username/projectname/logs/ccm.log. Start your instance running. After running this command you should run tailccm or taillogs which will show you when the initialization process has completed. It is also possible to pass arguments to ccm-start, which will be passed directly to the servlet container. For example: ccm-start -Djava.compiler=none This particular example will start the instance with the JIT compiler switched off. Stop the instance. The ccm-stop command only signals the servlet container to stop. Depending on what the instance is doing, it can take a short while for all processes to actually shut down. You should take care that all java processes have stopped before trying to start a new instance, as this can cause unpredictable results. If you want to work off of a different version of APLAWS or want to add a new application you will need to change your project.xml(). You will need to reconfigure the project area by running ccm-configure.sh. This command creates or updates the build.xml file in the project directory from the information contained in project.xml. It should be executed every time a change is made to project.xml. Unlike other commands, you must be in the same directory as project.xml when executing ccm-configure.sh. The dev directory is the top level development directory, it is located in /var/ccm-devel/dev/username/projectname. It contains information for the build process and all the source code in subdirectories. The dev directory contains a variety of configuration files for customizing ant, the servlet container, and APLAWS for your project. /var/ccm-devel/dev/username/projectname | | +--+ project.xml | | +--+ ant.properties | | +--+ config.vars | | +--+ enterprise.init | | +--+ application directory Contains a description of the project and its components. This file is used to generate build.xml, and to contains all the metadata required for creating a project package. It is described fully in the . This contains information required by ant, which is used for building &CCM; projects. The only option which may require alteration in this file is ccm.servlet.engine. For APLAWS projects, this should be set to resin. This file is used directly by ant, and should never be edited directly. It is created automatically by the ccm-configure.sh command from the information contained in project.xml. This file stores the configuration parameters for your development server. You will need to generate and edit this file to before you can get your server running. It is explained in more detail in the . This file is generated from config.vars and enterprise.init.in files in the application directories. This is the file that the server reads at startup. It is explained in more detail in the . This file describes the project and its components for the development and package building tools. Below is a sample project.xml file. <?xml version="1.0" encoding="ISO-8859-1"?> <ccm:project name="aplaws_borough" prettyName="APLAWS - Borough" type="project" versionFrom="aplaws_borough" extends="aplaws" extendsVersion="1.2.15" version="0.8.3" release="1" xmlns:ccm="http://ccm.redhat.com/ccm-project"> <!-- List all project specific applications here --> <ccm:build> <ccm:application name="aplaws_borough" prettyName="aplaws_borough" buildOrder="1"/> </ccm:build> <!-- List all shared, pre-built applications here --> <ccm:prebuilt> <!--<ccm:application name="cms" version="5.0.0" buildOrder="1"/> --> </ccm:prebuilt> </ccm:project> The attributes of the <ccm:project> tag define the highest level information about the project: The machine friendly name of the project. This is the name of the package when you create one, the name of a number of directories created when installing the package, and the name of the System V service the package creates. You will not typically change the value of this attribute once it has been set. This is a more descriptive name for the project for use when making a package. This attribute should always have the value project for APLAWS based projects. This is the name of an application subdirectory which contains a file called application.xml. If the versionFrom attribute is used, the version number for the package is taken from that file, instead of project.xml. The format of this file is explained in the . For APLAWS this will typically be your "-custom" directory containing custom styling. This is the version number of the project. The version number is used when an RPM is built from the development environment. If the versionFrom attribute exists it will be ignored and the version numbers in the application.xml will be used. Please see . This is the release number of the project. The version number is used when an RPM is built from the development environment. If the versionFrom attribute exists it will be ignored and the release number in the application.xml will be used. Please see This is the name of the project you are extending. In order for this to work, you will have to have installed the development package for that project. For example, for aplaws you will have installed a package called aplaws-devel-1.2.xx-y. You will not typically change the value of this attribute once it has been set. This is the version of the project which you are extending. For example, if you installed aplaws-devel-1.2.15-3, extendsVersion would be set to 1.2.15. Note that the release number ("-3") is omitted. You will update this value every time you install a new version of the aplaws-devel package. In addition to the above attributes, there are 2 sections where the structure of the application is defined. This section contains a list of applications which will be compiled and included in this project. For every application listed here, there must be an application subdirectory with the same name in the project directory. The buildOrder attribute is used to define which order the applications should be built in. If an application uses components provided by another application you will have to make sure they are built in the correct order. Another option not shown in the example above is the overwrite attribute. If set to yes, files in this application which overlap with existing files will overwrite the existing ones. This is primarily used for overriding XSL stylesheets. Thus in an APLAWS project, the application containing custom styling will typically use this option. This section contains a list of pre-built applications. These application do not need to be compiled, but will be deployed and packaged as part of this project. In the same way as the extends and extendsVersion attributes of <ccm:project> refer to the extended applications development package, the name and version attributes of <ccm:prebuilt> refer to the development package of a prebuilt application. APLAWS projects do not normally use any prebuilt applications. It is fine for this section to be empty or, as in the example above, the contents to be commented out. The server initialization file for a &CCM; based project is called enterprise.init. It is generated from a number of fragments in its component applications usually stored in application/etc/enterprise.init.in and from the parameter values set in config.vars. config.vars in turn, is created by pulling all placeholder variables out of enterprise.init.in fragments in a project's component applications. config.vars and enterprise.init does not exist at the beginning of the project. Here are the steps you must take at the beginning of a project. Run ant make-config () - this will generate config.vars. Edit config.vars and set the parameters to suit your project. Run ant make-init - This will generate enterprise.init from the values in config.vars and the various enterprise.init.in files (). You should always edit config.vars and not enterprise.init. The changes you make to config.vars is merged into enterprise.init with the ant command ant make-init (). APLAWS is designed to be configurable, however you can leave many of these parameters as they are to get a basic installation. At the bare minimum you will need to edit the following paramters. db-pass: Database password db-user: Database user debug-mode: Determines wheather whitespace is stripped from the HTML output. This should be set to true for development. jdbc-url: The JDBC URL to the database instance. For Oracle this value should match the entry in $ORACLE_HOME/network/admin/tnsnames.ora. For Postgres the entry should be jdbc:postgresql://servername/databasename. log-dir: This should point to /var/ccm-devel/web/username/projectname/logs for the taillogs to work. lucene-index-location: On a Postgres environment the search engine needs to be set to Lucene. The index location should be a directory that the development user can write to, the recommended directory is /var/ccm-devel/web/username/projectname/lucene.dat search-lucene-enabled: Set to false for Oracle, true for a Postgres environment. search-intermedia-enabled: Set to true for Oracle, false for Postgres. state-dir: The directory where server state files will be written, this should be a directory that's writable by the development user. The recommended directory is /var/ccm-devel/web/username/projectname/run. xslt-engine: Options are Xalan, Saxon, and JD.XSLT. The recommended parser is JD.XSLT. can leave many of this values as they are. But you will need to change the values of parameters such as db-pass, db-user, jdbc-url, log-dir, state-dir. The # sign is a comment marker, below is an annotated config.vars. # ACS initialization file admin-answer = 6 # Answer for web admin user's password reminder question admin-email = admin@example.com # email address of the web admin user admin-forename = Administrator # Forename of the web admin user admin-password = 123456 # web admin user's password admin-question = 12345 # web admin user password reminder question admin-surname = Account # web admin user's surname autoRegistration = true # redirect to registration form for unknown email addresses cache-expiry = 900 cache-peers = # peer servers for multi-tiered environment, leave blank for development caching-active = yes db-pass = ccm_xyz # Database password db-pool = 10 # database connection pool size db-user = ccm # Database useranme debug-mode = true # Turn HTML indentation on/off for development default-locale = en_GB default-scheme = http developer-support = false dispatcher-context-path = # leading URL stub dispatcher-servlet-path = dmi-active = false dmi-data-model-file = "/WEB-INF/sql/ccm-core/default/dmi/dmi-create.sql" dmi-xml-files = { "core-dmi.xml", "/WEB-INF/sql/ccm-core" } hostname = ccm.example.com # hostname of the server jdbc-url = jdbc:oracle:oci8:@(DESCRIPTION = (ADDRESS_LIST = (ADDRESS = (PROTOCOL = TCP)(HOST = oracle)(PORT = 1521)))(CONNECT_DATA = (SERVICE_NAME = ora8) (SRVR = DEDICATED))) #JDBC URL for the database server log-dir = /var/ccm-devel/web/username/projectname/logs # Log directory for the server, this value should point to the logs directory in your web directory log-level = warn log-size = 1000000 login-stylesheet = login_en.xsl lucene-index-location = /var/ccm-devel/web/username/projectname/lucene # If the database is Postgres the value should be changed to point to a directory in the web directory. page-map = WEB-INF/resources/hereford-login-page-map.xml permissionsDMLChecking = false rememberLoginByDefault = true search-intermedia-enabled = true # Change to false on a postgres environment search-lucene-enabled = false # Change to true on a postgres environment search-lucene-indexer-id = 0 server-name = localhost server-port = 8080 sitename = My APLAWS site # name of your website smtp-host = localhost state-dir = /var/ccm-devel/web/username/projectname/state # Value should point to a writable directory in the web directory subsite-dispatcher-class = com.arsdigita.ui.login.SubsiteDispatcher workflow-send-alerts = true workflow-sender-email = workflow-alerts@example.com # email notification sender for workflow alerts workflow-sender-given-name = Workflow # Name of alert sender workflow-sender-surname = Alerts # Surname of alert sender xslt-engine = JD.XSLT # XSLT parser, options are Saxon, Xalan, JD.XSLT. JD.XSLT is recommended xslt-timeout = 60 # interval for XSLT, set to a smaller number for development # CMS initialization file cms-item-adapters = /WEB-INF/resources/hereford-item-adapters.xml content-center-map = /WEB-INF/resources/content-center-map.xml content-digest-sender = article-digest@herefordshire.gov.uk content-section-name = content default-folder-template = /default/folder.jsp default-item-template = /default/item.jsp default-root-category = true forms-content-digest-sender = forms-digest@herefordshire.gov.uk forms-section-name = forms overdue-alert-interval = 24 overdue-duration = 96 overdue-max-alerts = 5 overdue-send-alerts = false publish-to-fs-servers = "http://servlet1/", "http://servlet2/" publish-to-fs-source = "http://servlet1/" publish-to-fs-this-server = "http://servlet1/" search-engine = intermedia template-root = /packages/content-section/templates # Portal initialization file portal-url = /portal/ # Forum initialization file, the third item in the forum list of lists is weather the forum is moderated or not adminCanEditPosts = true authorCanEditPosts = true digestUserEmail = digests forums = {{"forum1", "Forum #1", false, "nasakai@redhat.com", "Forum #1 Moderation" }, {"forum2", "Forum #2", false, "nasakai@redhat.com", "Forum #2 Moderation"}} replyHostName = devnull.redhat.com # search-spider-delay = 60 search-spider-frequency = 0 search-spider-urls = "http://www.redhat.com/", "http://www.example.org/" # Navigation initialization file default-content-section-url = "/content/" related-items-purpose = "DUBLINCORE" # Noticeboard initialization file adminCanEditNotices = true authorCanEditNotices = true noticeboards = {{"noticeboard", "Noticeboard"}} # chat-control-host = localhost chat-control-port = 8200 chat-public-host = localhost chat-public-port = 8200 chat-start-server = false # System Properties project-name = hereford Compilation and deployment of &CCM; and &CCM; based projects is done using ant. The options you can give to the ant command are called targets, and they are defined in the build.xml file. There are two types of ant targets that you will be using. The first set is the configuration targets such as ant make-config, ant update-config, and ant make-init. The second set are the deploy targets : The &CCM; build tools configures ant to compile or copy the files from the and the shared source directory into the web directory. The most commonly used deploy targets are the following: ant deploy-config, ant deploy, and ant deploy-application.For a complete list for your project, type ant on its own. Please see ,, , , , , , , Ant's configuration file is build.xml. This file is automatically generated by ccm-configure.sh from project.xml. Immediately after creating a project or making any change to project.xml, you must re-run ccm-configure.sh otherwise ant will not work as desired. While you should not need to edit build.xml yourself, if you would like to find out more, you can refer to the documentation at the ant homepage. All ant commands must be run from the top level project directory (the directory that contains build.xml. This should be the directory that you are in after you execute cddev (). Generates the configuration file config.vars by pulling all placeholder variables out of enterprise.init.in fragments in a project's component applications. Only run ant make-config once as subsequent executions will overwrite any customizations you have made to your config.vars . After the initial creation, keep it up-to-date with ant update-config (). Examines the enterprise.init.in files and adds any new/changed parameters to config.vars. This command will preserve the parameter values that you have set. This command will generate enterprise.init by concatenated all enterprise.init.in fragments in component applications and substituting values in config.vars. This only creates enterprise.init in the development directory. For it to be used it must be deployed. This is one of the tasks performed by the deploy target, or to deploy it on its own you can use ant deploy-config () This deploys only configuration information. This includes enterprise.init and web.xml. Use this target if you have made changes to either of these files, for example by using the make-init target. This command copies enterprise.init from the dev directory to the web directory. The file is located at /var/ccm-devel/web/username/projectname/webapps/ccm/WEB-INF/resources/enterprise.init. This deploys the entire project including all applications, the parent project if any and all configuration information. When you have only made changes to a single application and don't need to redeploy the whole project, use this target to deploy just a single application. For example, ant deploy-aplaws-custom will deploy only the aplaws-custom application. This removes all deployed files and directories, and all compiled classes from build directories. In other words this commands removes files in webapps/ccm in the development web directory (). Use this when you need to be sure that your project is rebuilt cleanly, for example after changing project.xml or before building a package for deployment on a live server. You will need to have a database instance that you can use for development. These steps should be conducted by your DBA, the following is the instructions for Postgres and Oracle environments. If you need instructions on setting up your database server please see . cdweb to change to the web directory and change into webapps/ccm/WEB-INF/sql. You will find a file called postgres-create.sh. Run this command with your database parameters to load the datamodel. $ sh postgres-create.sh dbname dbusername db server hostname cdweb to change to the web directory and change into webapps/ccm/WEB-INF/sql. You will find a file called oracle-create.sh, the argument for this script should be the database connection string you use to connect to the database via sqlplus. For example, if you connect to your Oracle instance with the following command: sqlplus my_aplaws/my_aplaws@myoracleserver Then you should run oracle-create.sh like this: $ sh oracle-create.sh my_aplaws/my_aplaws@myoracleserver