This page is under heavy revision. Please refer to
http://doc.desktopgrid.hu/
for up-to-date information and documentation.
Deploying applications on a BOINC server

  • Keep in mind to maintain your server as a server administrator user and not via the root or a simple user account.
  • Also keep in mind to always stop your project before maintenance, by executing the stop command. After you have finished maintenance restart the server with the start command. All the effects of your maintenance will take effect when you restart the server.
  • Keep in mind that all of the project maintenance procedures have to be carried out with a user administrator having boinc project admin rights. Do not forget to "sudo" to the boinc admin user account, which also has the home folder set to /var/lib/boinc/<project short name>. Most of the files and folders mentioned in this section are located on this path, in the subdirectory named project.
After you have prepared and compiled your application to be executed in the BOINC environment, you have to deploy the application on the server. Deploying an application is an easy task and has to be carried out only once for each application.

Installing the client application

The following examples are going to be demonstrated with the example application called Uppercase. Do not forget that the home folder of the project is /var/lib/boinc/<project's short name>/project and to access this folder with a user account having project administrator rights. The steps of the install process is as follows:
  • Add the application to the project.xml file of your project.
      <app>
        <name>uppercase-example</name>
        <user_friendly_name>Example Application</user_friendly_name>
      </app>
      
    The name tag will identify your application in the project, while the users will see the user friendly name. It is very important that you give the exact same name here what you named the folder in /<project name>/project/apps/

  • Copy the executable and all of the necessary files of the application in the apps folder of your project. The naming convention of the application executables and directories in BOINC is: <name>_<version #>_<platform>. There are several pre-defined platforms in BOINC. For example the Linux Intel® x86 platform is identified by the i686-pc-linux-gnu string and the Windows Intel® x86 platform is identified by windows_intelx86. The version numbering should start from 1.00 and increment in 0.01 steps for each new version of the application.

    Please note, that in case of a windows application, the directory name has to match the name of the application exactly, also containing any extensions, like '.exe'.

    Follow the steps to create a Linux binary for Linux based clients.

      cd ~/project/apps/
      mkdir uppercase-example
      cd uppercase-example
      mkdir uppercase-example_1.00_i686-pc-linux-gnu.exe
      cp <path of compilation>/uppercase-example-client uppercase-example_1.00_i686-pc-linux-gnu/uppercase-example_1.00_i686-pc-linux-gnu
      

    Please note, that if you want to create a binary for Windows based clients, you will have to set up an environment for compiling applications on Windows.


  • The application has to be signed to ensure the integrity and security of the application. This step is optional, since the final step of executing the update_versions script can carry out the application signing procedure automatically, if it finds the signatures to be missing. Before signing the executables ensure that all of the executable files has been granted executable rights on the server, including Windows executables. If an application consists of multiple files (e.g.: like windows DLLs), then all of files has to be signed separately.
      sign_executable uppercase-example_1.00_i686-pc-linux-gnu ../../../keys/code_sign_private >uppercase-example_1.00_i686-pc-linux-gnu.sig
      
    The key files of your project are located in the ~/project/keys folder. If you prepare to run a public desktopgrid, you should keep your private keys in a secure place (e.g.: on a removable media, like a CD).

  • Install a validator for your application. The job of the validator is to ensure that the results returning from the clients are intact and has not been altered in a bad way on the client. This is an application dependent task, so the creator of the application has to write the validator as well, which compares returning results and decide whether they are acceptable or not. If you run your desktopgrid in a local environment and does not use redundancy than it is not necessary to validate the results. However, a validator is still needed. For this an example validator can be used which is provided in the server package. If you use your own validator copy the executable in the bin directory of your project. To install the example validator add the followings to the config.xml file of your project, pay attention to the executable name if you use your own validator.
      <daemon>
        <cmd>
          sample_trivial_validator -d 3 -app uppercase-example
        </cmd>
      </daemon>
      

  • Execute the xadd command if you are installing an application for the first time. This script reads the contents of project.xml and commits any new applications or platforms found into the database of the project. Later, when updating the version of your application you do not have to run this command.

  • Execute the update_versions command, to commit the latest version of your application in the database of your desktopgrid. This command has to be executed, whenever you install a new version of your application.

Installing the master application

Log in to the server as a project administrator and go to the home directory (/var/lib/boinc/<short name of project>/) and create a directory called <application name>-master
  mkdir uppercase-example-master
  
Copy the file named 'dcapi.conf' (located in /usr/share/doc/libdcapi-common-dev/examples/uppercase-with-callback) in this directory and rename it to 'uppercase-example-master.conf'. Personalize this configuration file similarly as the example below. Don't forget to generate a unique uuid and use it instead of the example below. You can use the uuidgen command-line utility which can be found in the uuid-runtime package.
  WorkingDirectory = /var/lib/boinc/<project's short name>/uppercase-example-master
  
  InstanceUUID = fc7286ea-d8ab-4304-be55-84c098d7db42
  
  BoincConfigXML = /var/lib/boinc/<project's short name>/project/config.xml
  
  ProjectRootDir = /var/lib/boinc/<project's short name>/project
  

The input of the example application has to be located in the WorkingDirectory, which has been set in the configuration file of the above example. Create a file called input.txt in this directory and fill it with several lines of arbitrary text. The master application will create workunits by splitting this file into workunits. The master application will create 'number of lines in input.txt divided by 20' number of workunits. For example if input.txt has 20 lines the master application will create only 1 workunit, or if input.txt has 64 lines than the master application will create 4 workunits, however the 4th workunit will only has 4 lines to process, while the first 3 will have 20.

Copy the executable of the master application in the bin directory of your project.

  cp uppercase-example-master /var/lib/boinc/<project's short name>/project/bin
  
Run the master by executing:
  uppercase-example-master -c /var/lib/boinc/<project's short name>/uppercase-example-master/uppercase-example-master.conf
  
You can also put the master executable to the bin directory of the project and create a new <daemon> tag for it in the config.xml file. The <daemon> tag has to be nested in the <daemons> tag within the config.xml file. This way the master application will start and stop with the server.

  <daemon>
    <cmd>
      uppercase-example-master -c /var/lib/boinc/<project's short name>/uppercase-example-master/uppercase-example-master.conf
    </cmd>
  </daemon>
  
Please note that the Uppercase example application is already in the project.xml file. There is no need to add it again.

If by any chance the daemon would not start then try to give the full path to uppercase-example-master executable in the bin directory.

From now on, the start script of the BOINC server will execute the example master application as well, which will create workunits based on the settings carried out above. After the example master application has created the workunits, it will wait for any results available and process them upon the BOINC server reports that they have been processed and are available for assimilating.

To enable the periodically running tasks change the 1 in the <disable> tags to 0 for each task.

Now that you have installed a BOINC server, developed and deployed an application, you have to connect some clients to the server, which can start processing the workunits.