19236
Comment: pointing to readily available wrapper.
|
19109
more on getting the web page up
|
Deletions are marked like this. | Additions are marked like this. |
Line 260: | Line 260: |
=== Showing index.php by default === With a typical Debian apache setting, the expected BOINC web interface only shows up after clicking on index.php. Edit /etc/apache2/sites-enabled/${filesprojectname}.httpd.conf as follows to show index.php files directly: {{{ <Directory "...fileprojectname.html"> Options Indexes FollowSymlinks MultiViews +ExecCGI ... # Adding these three lines <IfModule mod_dir.c> DirectoryIndex index.php </IfModule> # </Directory> }}} |
|
Line 262: | Line 278: |
It remains mysterious that this was not already performed by "make_project". The web pages show whenever there should be the project name, the string "REPLACE WITH PROJECT NAME". To fix this, perform {{{ [ -r . ~/.boincproject.sh ] && . . ~/.boincproject.sh if [ -z "$installroot" -o -z "$fileprojectname" -o -z "$niceprojectname" ]; then echo "Variables niceprojectname, installroot or projectname not set." echo "Warning, completely unnecessary error, not dramatic, just ugly." elif ! cd "$installroot"/"$fileprojectname"; then echo "Could not change to '$installroot'/'$fileprojectname'." else sudo sed -i "s/REPLACE WITH PROJECT NAME/$niceprojectname/" html/project/project.inc fi }}} Let us just presume that there is no "/" character in the niceprojectname. You should manually edit that file to set email addresses right. The project start page is not appreciated by everyone. Amend it in './html/user/index.php' but wary of subsequent updates. Many are providing a home page to their project that is kept separate from the BOINC-intrinsic workload distribution, i.e. that BOINC-provided index.php page. |
The web pages show whenever there should be the project name the string "REPLACE WITH PROJECT NAME". To fix this and other things like your public email address, edit html/project/project.inc . The project start page is not appreciated by everyone. Amend it in './html/user/index.php' but wary of subsequent updates. Many are providing a home page to their project that is kept separate from the BOINC-intrinsic workload distribution, i.e. that BOINC-provided index.php page. |
THESE PAGES ARE STILL UNDER DEVELOPMENT
This tutorial will help you create BOINC project with Debian server without using virtual images provide from BOINC. See BOINC/Server for an overview on BOINC-Server with Debian related issues. For an overview and guide on how to compile the BOINC package from the pkg-boinc git repository, see BOINC/Development/GitUsage.
Contents
To see more info about how to install and config BOINC server, please look at BOINC project wiki and the "See also" section on this page.
Preparations
The BOINC server as compiled from the BOINC sources does not perform directly. That BOINC server is "only" the skeleton for the real server. For that reason, the Debian package is named no longer "boinc-server" but now presents itself as "boinc-server-maker".
In the following, please distinguish
- the folder to which the files of the BOINC server templates install ('/usr/share/boinc-server')
- the name of the Debian package providing those files ('boinc-server-maker')
- the location of your very own project ('you/name/it')
The preparation from the Debian sources is not too different from a preparation from the original source tree. Debian should just shorten the process to a first success.
Install BOINC Server Template files
This section first explains the installation of the BOINC server template sources from the source tree and then the same for those using the Debian boinc-server-maker package.
Installation according to the books - ''without'' the Debian server package
Install BOINC server dependencies :
sudo apt-get install subversion build-essential apache2 php5 mysql-server php5-gd php5-cli php5-mysql python-mysqldb libtool automake autoconf pkg-config libmysql++-dev libssl-dev
Create a user and a group for BOINC and add www-data to that group :
sudo addgroup --system boincadm sudo adduser www-data boincadm
Download BOINC source :
svn co http://boinc.berkeley.edu/svn/branches/server_stable boinc
Compile BOINC :
cd boinc ./_autosetup ./configure --disable-client make
Installation ''with'' the Debian server package
Install boinc-server-maker package from unstable :
sudo apt-get install boinc-server-maker
Project-specific configuration
The preparation of the final project from the BOINC server template is a manual process. That should be applied only once for every project and then for updates of the BOINC server sources. One could (in principle) prepare Debian packages for such project specific configurations. The boinc-server-maker package described on this page would then become a build dependency for the project. This is likely to happen but has not yet been addressed.
Create and config BOINC project
The BOINC server as compiled from the BOINC sources does not perform directly.
The following needs to be performed for every project, with or without the Debian BOINC server package. In the following we will work on a single BASH shell. This allows us to use mostly self-explanatory variables to help your local adaptation.
To help working consistently on multiple shells, we need a place to redirect the parameters of the project configuration. We do that only to help ourselves; the BOINC code will not use it.
Initialisation of the configuration
For a first start of a project create the file that the project parameters shall be stored in.
echo > ~/.boincproject.sh chmod 600 ~/.boincproject.sh
Parameters for the MySQL database
cat << EODBCONFIG >> ~/.boincproject.sh # password for write access to your prject database pw=MYSQLPASSWORDFORBOINCUSER # name of the MySQL database dbprojectname=boinctest EODBCONFIG
For your convenience you may copy above code and then use an editor to change it.
Create MySQL database for BOINC project
With the variables defined before, you can just copy and pasted the code below. The password asked is the password for the root user to access the database.
# read config if available [ -r ~/.boincproject.sh ] && . ~/.boincproject.sh if ! echo "DROP USER 'boincadm'@'localhost'" | mysql -u root -p; then echo "If the removal of the previous user fails because the user is not existing, then this does not matter. Other errors would be required a manual removal." fi if [ -z "$dbprojectname" ]; then echo "Variable 'dbprojectname' not set"; elif [ -z "$pw" ]; then echo "Variable 'pw' not set"; else # piping commands to mysql shell cat <<EOMYSQL | mysql -u root -p mysql DROP DATABASE IF EXISTS $dbprojectname; CREATE DATABASE IF NOT EXISTS $dbprojectname; CREATE USER 'boincadm'@'localhost' IDENTIFIED BY '$pw'; GRANT ALL PRIVILEGES ON $dbprojectname.* TO 'boincadm'@'localhost'; EOMYSQL fi
Create project
Please replace a.b.c.d with your full hostname or your server's IP address. If you only have dynamic IP addresses, then this is unfortunate, but investigate the service of dyndns.org to help out.
cat <<EOCONF >> ~/.boincproject.sh # address of host (via DNS or IP number) at which project server shall be reached hosturl=http://a.b.c.d # name of folder in which data shall be stored, also becomes part of project URL fileprojectname=$dbprojectname # more human-compatible way to read the project name niceprojectname="BoincTestProject@Home" # location at which sources shall be kept installroot=/var/tmp/boinc EOCONF
Again, please edit '~/.boincproject.sh' with a text editor if required. This example installroot is where you cannot harm anything. Some linux distributions may however have that directory cleaned at boot time. Please adjust.
Installation according to the books - ''without'' the Debian server package
The installation is expected to happen from within the BOINC source tree.
[ -r ~/.boincproject.sh ] && . ~/.boincproject.sh if [ -z "$installroot" -o -z "$hosturl" -o -z "$dbprojectname" -o -z "$pw" \ -o -z "$niceprojectname" -o -z "$fileprojectname" ] ; then echo "Missing configuration parameter." else [ -d "$installroot" ] || sudo mkdir -p "$installroot" sudo ./tools/make_project --url_base "$hosturl" --db_name "$dbprojectname" \ --db_user boincadm --db_passwd "$pw" --drop_db_first \ --project_root /var/www/boinc/$fileprojectname \ "$fileprojectname" "$niceprojectname" fi
Installation ''with'' the Debian server package
If you use boinc-server package you need to use this command instead:
[ -r ~/.boincproject.sh ] && . ~/.boincproject.sh [ -d "$installroot" ] || sudo mkdir "$installroot" sudo PYTHONPATH=$PYTHONPATH:/usr/share/pyshared/Boinc/ /usr/share/boinc-server/tools/make_project --url_base "$hosturl" --db_name "$dbprojectname" --db_user boincadm --db_passwd "$pw" --drop_db_first --project_root "$installroot"/"$fileprojectname" --srcdir /usr/share/boinc-server/ "$fileprojectname" "$niceprojectname"
The '--test_app' flag is omitted to help the understanding of the setup and since for Debian the required example_app is not compiled by default in the current version (6.12.8-2) of the package.
The screen output should not look too different from
Creating project 'BoincTestProject@Home' (short name 'boinctest'): PROJECT_ROOT = /var/tmp/boinc/boinctest/ URL_BASE = http://boincserver.dyndns.org/ HTML_USER_URL = http://boincserver.dyndns.org/boinctest/ HTML_OPS_URL = http://boincserver.dyndns.org/boinctest_ops/ CGI_URL = http://boincserver.dyndns.org/boinctest_cgi/ KEY_DIR = /var/tmp/boinc/boinctest/keys/ DB_NAME = boinctest DB_HOST = Delete /var/tmp/boinc/boinctest/? [y/N] y Deleting /var/tmp/boinc/boinctest/ Continue? [Y/n] Setting up server: creating directories Keys don't exist in /var/tmp/boinc/boinctest/keys/; generate them? [Y/n] Setting up server files: generating keys Setting up server files: copying files Setting up database Setting up server files: writing config files Setting up server files: linking cgi programs update_translations finished Done installing default daemons. Done creating project. Please view /var/tmp/boinc/boinctest/boinctest.readme for important additional instructions.
That 'boinctest.readme' basically says what the next section is presenting.
Continue - with or without the Debian BOINC server package
Adjusting permissions for project directory
Make sure the configuration variables are set
[ -r ~/.boincproject.sh ] && . ~/.boincproject.sh
Change files and directories permission:
if [ -z "$installroot" -o -z "$fileprojectname" ]; then echo "Not all variables are set for the configuration" echo "Error, do not continue." elif [ ! -d "$installroot"/"$fileprojectname" ]; then echo "The directory '$installroot/'$fileprojectname' is not existing" echo "Error, do not continue." else cd "$installroot"/"$fileprojectname" sudo chown root:boincadm -R . sudo chmod g+w -R . sudo chmod 02770 -R upload html/cache html/inc html/languages \ html/languages/compiled html/user_profile fi
A successful execution will once ask for the user's sudo password but otherwise remain quiet.
If those permissions are sufficient depends on the user the the web service runs with. For Debian, running apache as user www-data, the include files need to be accessible. Those they should be with www-data added to the group boincadm with those files group accessible and group writable. However, there seem to be some remaining issues. To circumvent them, run
if [ -d html/inc -a -d cgi-bin ]; then sudo chmod o+x html/inc sudo chmod -R o+r html/inc sudo chmod o+x html/languages/ sudo chmod o+x html/languages/compiled else echo "You are not in your project directory" fi
The "-r" is important to reach all the files since the directory cannot be read before the execution of "sudo".
Automated restart upon failure
Add project cronjob:
sudo crontab -e
Then add this line to editor appear after run command above
0,5,10,15,20,25,30,35,40,45,50,55 * * * * /var/boinc/testproj/bin/start --cron
Verify that the cron entry was indeed accepted
sudo crontab -l
Config password for BOINC server administrative page:
sudo htpasswd -c html/ops/.htpasswd USERNAME
Config Apache to call BOINC server
sudo cp ${fileprojectname}.httpd.conf /etc/apache2/sites-available/ sudo a2ensite ${fileprojectname}.httpd.conf sudo /etc/init.d/apache2 reload
Test web interface
The web site should now be accessible. It should be available as an alias "$fileprojectname", please look it up in "/etc/apache2/sites-enabled/${filesprojectname}.httpd.conf". You will find the automated home page to need some further manual adjustments - which does not really encourage to update the server version too frequently, we presume.
If the home page does not show up then there may be some missing file or some bogus file permission. The inspection of "/var/log/apache/error.log" should bring sufficient insights to fix the issue.
Showing index.php by default
With a typical Debian apache setting, the expected BOINC web interface only shows up after clicking on index.php. Edit /etc/apache2/sites-enabled/${filesprojectname}.httpd.conf as follows to show index.php files directly:
<Directory "...fileprojectname.html"> Options Indexes FollowSymlinks MultiViews +ExecCGI ... # Adding these three lines <IfModule mod_dir.c> DirectoryIndex index.php </IfModule> # </Directory>
Substituting ProjectName in *.html and *.php
The web pages show whenever there should be the project name the string "REPLACE WITH PROJECT NAME". To fix this and other things like your public email address, edit html/project/project.inc .
The project start page is not appreciated by everyone. Amend it in './html/user/index.php' but wary of subsequent updates. Many are providing a home page to their project that is kept separate from the BOINC-intrinsic workload distribution, i.e. that BOINC-provided index.php page.
Add functionality
Configure and start BOINC demons
Please stay in that project directory and just use the default configuration as a start.
Read information from file 'project.xml' and put into the database
sudo bin/xadd
The tool xadd configures the project by parsing the 'project.xml' file. That 'project.xml' file initially only lists the most common platforms. Then it mentions the application that should be supported, which is 'uppercase'.
add the binary to be distributed to the clients. For the applications in 'project.xml', a folder in the 'apps' directory must be created and the respective binary be placed into that.
to be written, this is just guesswork for the very moment. sudo mkdir apps/uppercase sudo chown root:boincadm apps/uppercase sudo chmod 770 apps/uppercase # works for the Debian boinc-server package: sudo cp /usr/lib/boinc-server/apps/upper_case apps/uppercase/uppercase_$(arch)-pc-linux-gnu # copy it from your source directory if not running that package
The $(arch) identifies the platform that this installation is performed on and consequently that the binary in /usr/lib/boinc-server is compiled for. The information on the availability of that binary needs to be communicated to the database by executing the update_versions tool by a mere
sudo PYTHONPATH=/usr/share/boinc-server/py bin/update_versions
.start the demons
sudo bin/start
Running start, this should show something like
Entering ENABLED mode Starting daemons Starting daemon: feeder -d 3 Starting daemon: transitioner -d 3 Starting daemon: file_deleter -d 3
and after some academic minute the shell prompt should return. The UNIX tool top should just show your regular BOINC work units (assuming that your server remains a good client until it is busy). A "ps aux | tail -20" should list something like
root 4551 0.4 2.1 46864 21776 ? S 10:33 0:00 feeder -d 3 root 4553 0.0 0.2 35312 3004 ? S 10:33 0:00 transitioner -d 3 root 4555 0.0 0.2 27336 2240 ? S 10:33 0:00 file_deleter -d 3
Something lets me think that those processes should better run as "boincadm" than via 'sudo', but, well, let's be happy for now.
Add your own application
The only thing that counts to have is the application that helps your very personal task at hand. This will be addressed in the upcoming section. The section at hand will take one of the example projects.
When compiling the sources oneself
When building the
Compile sample application :
cd ~/boinc/samples/wrapper make
Setup sample application :
cd "$installroot"/"$fileprojectname" sudo ./html/ops/single_job_setup.php ~/boinc/samples
This 2nd step then demands to add two binaries to the local config.xml file, have those electronically signed by
sudo bin/update_versions
. Once done, one shall restart BOINC
sudo bin/stop sudo bin/start
.
When starting from the Debian package
The wrapper application is already coming with the boinc-server-maker package in /usr/lib/boinc-server/apps/wrapper. Its source code is in "/usr/share/doc/boinc-server-maker/examples/wrapper/". The Makefiles have been adjusted to all the direct compilation of that binary outside the source tree of BOINC.
Config clients
The project should now be ready to run a couple of work units. Please use any Linux BOINC client. The Debian boinc-client package will do. It needs to be Linux since our application was yet only prepared for this OS. The project URL is $hosturl/$fileprojectname.
Management of your own project
To be written.
Why to use (or not to use) the Debian BOINC server package
The concept of the BOINC server package is slightly irritating in that it itself is not a working server but something from which a server infrastructure is generated. It provides all the binaries and header files for local developments and thus saves some considerable time to prepare such and ensures to have all the libraries in place that the community has determined to be of help.
The typical advantages of Debian do apply. It should for instance be possible, to change the server architecture at any time from one platform to another. If it is running on your laptop, it should e.g. also run on an ARM netplug.
The package is still too experimental to use in a production environment. But, hey, we will be getting there over time.
See also
Build demon status for unstable
Build demon status for experimental
BOINC Software Development Wiki
SingleJob setup used for example
xadd - adding platforms and applications
update_versions - adding or updating versions of the application
start - starting the demons
wrapper application to boincify regular applications
UNIX Project Package thoughts by upstream
- Tutorials by
spy-hill.net (neat and extensive, some stale links)
Black Sheep Software (command line only)
BOINC Article in Linux Magazine issue 71 by Marc Seil (2006) "Idle Cycles".