The make_project script

The make_project script creates the server components of a BOINC project. To use it, set up a BOINC server. Then, for example, type:

cd BOINC_SOURCE/tools
make_project --test_app cplan

This creates a project with master URL http://HOSTNAME/cplan/ whose directory structure is rooted at $HOME/projects/cplan.

More specifically, make_project does the following:

• Create the project directory and its subdirectories.
• Create the project's encryption keys if necessary. NOTE: before making the project visible to the public, you must move the code-signing private key to a highly secure (preferably non-networked) host, and delete it from the server host.
• Create and initialize the MySQL database
• Copy source and executable files
• Generate the project's configuration file.

With the --test_app option (recommended) the project will have a test application (uppercase) and daemons to generate and handle work for this application. This lets you quickly check that the project is working; you can remove the test application later by editing config.xml.

The following steps complete the project setup:

• Insert PROJECT_NAME.http.conf into /etc/apache/httpd.conf (path varies), or Include it from that file.
• Run crontab -e, and add an entry to run the project's cron script:

   0,5,10,15,20,25,30,35,40,45,50,55 * * * * PROJECT_HOME/bin/start --cron
  

(if cron cannot run 'start', try using a helper script to set PATH and PYTHONPATH)

• Run bin/xadd and bin/update_versions in the project's home directory.
• Run bin/start.

The script prints instructions for these steps.

The command-line syntax is as follows:

make_project [options] project_name [ 'Project Long Name ' ]

Options are as follows (normally you don't need to include any of them):

directory options

--project_root	Project root directory path. Default: $HOME/projects/PROJECT_NAME
--key_dir	Where keys are stored. Default: PROJECT_ROOT/keys
--url_base	Determines master URL Default: http://HOSTNAME
--no_query	Accept all directories without yes/no query
--delete_prev_inst	Delete project-root first (from prev installation)

URL options

--html_user_url	User URL. Default: URL_BASE/PROJECT_NAME/
--html_ops_url	Admin URL. Default: URL_BASE/PROJECT_NAME_ops/
--cgi_url	CGI URL. Default: URL_BASE/PROJECT_cgi/

database options

--db_host	Database host. Default: none (this host)
--db_name	Database name. Default: PROJECT_NAME
--db_user	Database user. Default: current user
--db_passwd	Database password. Default: None
--drop_db_first	Drop database first (from prev installation)

Miscellaneous options

--test_app	install test application
--verbose={0,1,2}	verbosity level, default 1
-h or --help	Show options

Example: Legacy application plus Wrapper setup

Assuming you have a legacy application (i. e., an executable not using the Boinc API), you can make it run under BOINC through the use of the wrapper application. In case you don't already have that application, you can download it, along with some other samples, doing 'svn co http://boinc.berkeley.edu/svn/trunk/boinc_samples'. Let's say that your application is located at /home/ABC/ and the name of the executable is abc. Assume that the command needed to run it is:

> abc -i input.in -p parameters.in -o output.out

Now, do the following (the paths I use are those corresponding to the Debian virtual machine; adjust accordingly to your installation):

> cd /home/boincadm/boinc_samples/wrapper
> ln -s `g++ -print-file-name=libstdc++.a`

Edit the Makefile for wrapper and change the BOINC_DIR variable according to your installation (in the Debian virtual machine this would be BOINC_DIR=/home/boincadm/boinc_trunk).

> make

So far, you have created the wrapper executable.

> cd /home/boincadm/boinc_trunk/tools
> ./make_project abc (or any other name you want to use)
> su
> cat /home/boincadm/projects/abc/abc.httpd.conf >> /etc/apache2/httpd.conf
> apache2ctl restart
> exit

Now, you have created the directory structure for your project, named abc, with some project's control files. Also, you have modified the Apache configuration to make it serve your project.

> cd /home/boincadm/projects/abc
> crontab abc.cronjob
> cd apps; mkdir abc; cd abc
> mkdir wrapper_1.01_i686-pc-linux-gnu (this name has the format wrapper_version_architecture-operating-system)
> cd wrapper_1.01_i686-pc-linux-gnu
> cp /home/ABC/abc abc_1.01_i686-pc-linux-gnu (use same format as with the directory above)
> cp /home/boincadm/boinc_samples/wrapper/wrapper wrapper_1.01_i686-pc-linux-gnu
> vi job.xml=job_1.01.xml

The contents of this file, job.xml=job_1.01.xml, for the abc application are

<job_desc>
    <task>
        <application>abc_1.01_i686-pc-linux-gnu</application>
          <command_line>
             -i input.in -p parameters.in -o output.out
          </command_line>
    </task>
</job_desc>

> cd /home/boincadm/projects/abc/templates
> vi abc_wu (this is the work-unit template)

Contents of abc_wu:

<file_info>
    <number>0</number>
</file_info>
<file_info>
    <number>1</number>
</file_info>
<workunit>
    <file_ref>
        <file_number>0</file_number>
        <open_name>input.in</open_name>
        <copy_file/>
    </file_ref>
    <file_ref>
        <file_number>1</file_number>
        <open_name>parameters.in</open_name>
    </file_ref>
    <min_quorum>1</min_quorum>
    <target_nresults>1</target_nresults>
    <credit>1</credit>
    <rsc_fpops_bound>1000000000000</rsc_fpops_bound>
    <rsc_fpops_est>1000000000000</rsc_fpops_est>
</workunit>

> vi abc_result (this is the results template)

Contents of abc_result:

<file_info>
    <name><OUTFILE_0/></name>
    <generated_locally/>
    <upload_when_present/>
    <max_nbytes>10000000</max_nbytes>
    <url><UPLOAD_URL/></url>
</file_info>
<result>
    <file_ref>
        <file_name><OUTFILE_0/></file_name>
        <open_name>output.out</open_name>
        <copy_file/>
    </file_ref>
</result>

> cd ..
> vi project.xml

and change the application name in the last few lines of the file:

...
    <app>
       <name>abc</name>
       <user_friendly_name>abc</user_friendly_name>
    </app>
</boinc>

Check the file 'config.xml' to see if the IP address there is correct and change the value of <disable_account_creation> from 1 to 0 if you want to enable account creations. Also, at the end of this file is where you can change or add daemons to control your application.

Now, you have all the files in place, so let's tell BOINC to add the project to the database and to copy the files it will need to the download directory. Then, start the project's daemons:

> bin/xadd
> bin/update_versions
> bin/start

Put your input files (input.in and parameters.in) in /home/boincadm/projects/abc/download/. Then do:

> cp download/input.in `bin/dir_hier_path input.in`
> cp download/parameters.in `bin/dir_hier_path parameters.in`
> bin/create_work -appname abc -wu_name abc-nodelete01 -wu_template templates/abc_wu -result_template templates/abc_result input.in parameters.in

The last step creates a workunit. This will be sent to a client attached to this project, who will perform the required work and return the results to the upload directory.

*Note: The order of the input files when issuing the create_work command has to be the same as in the workunit template file (abc_wu above). If this is not satisfied, the client will produce errors when processing the wu. Typical error will be:

Task wu_name exited with zero status but no 'finished' file
If this happens repeatedly you may need to reset the project

The project should be functional and accessible now to any BOINC client.