docs

svn path=/trunk/boinc/; revision=521

doc/create_project.html

@@ -47,12 +47,12 @@ How to install and configure the BOINC server software.
 <ul>
 <li> <a href=road_map.html>Road map of the BOINC software</a>
 <li> <a href=server_components.html>Server components</a>
+<li> <a href=single_host_server.html>Setting up a single-host server</a>
 <li> <a href=database_setup.html>Setting up the BOINC database</a>
 <li> <a href=key_setup.html>Creating encryption keys</a>
 <li> <a href=sched_server_setup.html>Setting up a scheduling server</a>
 <li> <a href=web_site.html>Setting up a web site</a>
 <li> <a href=data_server_setup.html>Setting up a data server</a>
-<li> <a href=single_host_server.html>Setting up a single-host server</a>
 <li> <a href=test.html>Test applications and scripts</a>
 <li> <a href=project_startup.html>Project startup checklist</a>
 

doc/server_components.html

@@ -10,7 +10,13 @@ A BOINC server consists of the following components:
 <li> Web server(s)
 <li> Data server(s)
 </ul>
-These components may all run on a single host, or on separate hosts.
+These components may all run on a single host,
+or on separate hosts.
 Some of them, as indicated, may be replicated.
 
 <p>
+These components are described in detail in separate documents,
+which are required reading if you want to separate
+and/or replicate the components.
+To set up a basic server where all components run on a single host,
+you can use a simple <a href=single_host_server.html>server setup script</a>.

doc/single_host_server.html

@@ -1,4 +1,160 @@
 <title>Setting up a single-host server</title>
 <h2>Setting up a single-host server</h2>
 
-<p>
+<p>
+BOINC provides a set of scripts for setting up
+and controlling a BOINC server complex.
+These scripts require all the server components to run on a single host.
+This has been tested only on Linux and Solaris hosts;
+it may work with small modifications on Windows also.
+<p>
+The scripts can be used to create multiple BOINC projects on the same host.
+This can be handy for creating separate projects for testing and debugging.
+In fact, the scripts are part of a general
+<a href=test.html>testing framework</a>
+that allows multiple developers to work independently on
+a single host, with each developer able to create multiple projects.
+<p>
+Install the following software on the server host:
+<ul>
+<li> MySQL, version 3.23 or later
+<li> PHP, version 4.2.3 or later
+<li> Apache, linked with the PHP module
+</ul>
+
+<h3>Directory structure</h3>
+
+Designate a "BOINC projects" directory on the server host.
+The scripts will create subdirectories as follows:
+<pre>
+boinc_projects/
+    proj1/
+        cgi/
+        download/
+        html_ops/
+        html_user/
+        keys/
+        upload/
+    proj2/
+    ...
+</pre>
+where proj1, proj2 etc. are the names of the projects you create.
+Each project directory contains:
+<ul>
+<li> cgi: copies of the BOINC server programs, and a configuration file.
+<li> download: storage for data server downloads.
+<li> html_ops: copies of PHP files for project management.
+<li> html_user: copies of PHP files for the public web site.
+<li> keys: encryption keys used by the project.
+<li> upload: storage for data server uploads.
+</ul>
+
+<h3>Web server configuration</h3>
+<p>
+Create two directories, used to store symbolic links
+to project-specific HTML and CGI directories.
+You might call these boinc_html and boinc_cgi.
+Then edit your Apache configuration file,
+adding something like the following:
+
+<pre>
+Alias /david/ "/users/david/boinc_html/"
+&lt;Directory "/users/david/boinc_html">
+    Options Indexes FollowSymlinks MultiViews
+    AllowOverride None
+    Order allow,deny
+    Allow from all
+&lt;/Directory>
+
+ScriptAlias /david_cgi/ "/users/david/boinc_cgi/"
+&lt;Directory "/users/david/boinc_cgi">
+    AllowOverride None
+    Options FollowSymLinks
+    Order allow,deny
+    Allow from all
+&lt;/Directory>
+
+</pre>
+
+<h3>Environment variabless</h3>
+
+Define the following environment variables:
+<p>
+<table border=1 cellpadding=8>
+<tr><td>BOINC_PROJECTS_DIR</td>
+
+<tr><td> BOINC_USER_NAME</td>
+<td> This is used as a component of database names,
+and is prepended to web error log entries.
+Relevant if multiple developers share one host.
+/td></tr>
+<tr><td> BOINC_SRC_DIR</td>
+<td> Path of directory where BOINC source code is</td></tr>
+<tr><td> BOINC_CGI_DIR</td>
+<td> Path of the CGI symbolic-link directory (see above).</td></tr>
+<tr><td> BOINC_CGI_URL</td>
+<td> URL of the CGI symbolic-link directory.</td></tr>
+<tr><td> BOINC_HTML_DIR</td>
+<td> path of a HTML symbolic-link directory (see above)</td></tr>
+<tr><td> BOINC_HTML_URL</td>
+<td> URL of the HTML symbolic-link directory</td></tr>
+<tr><td> BOINC_SHMEM_KEY</td>
+<td> Identifier for shared-memory segment (use any 31-bit number
+that doesn't conflict with current segments)</td></tr>
+</table>
+
+<p>
+For example, you might execute the following shell script:
+<pre>
+setenv BOINC_PROJECTS_DIR   /home/david/boinc_projects
+setenv BOINC_USER_NAME      david
+setenv BOINC_SRC_DIR        /home/david/boinc_cvs/boinc
+setenv BOINC_CGI_DIR        /home/david/cgi-bin
+setenv BOINC_CGI_URL        http://localhost/cgi-bin
+setenv BOINC_HTML_DIR       /home/david/html
+setenv BOINC_HTML_URL       http://localhost
+setenv BOINC_SHMEM_KEY      0x3abc1234
+</pre>
+
+<h3>Creating the server</h3>
+<p>
+Once you've done all the above steps,
+edit the script make_project.php
+in the test directory of the BOINC source tree,
+adding your application name.
+Then execute this script.
+This does the following:
+
+<ul>
+<li> Create the project directory and its subdirectories.
+<li> Create the project's encryption keys.
+NOTE: before making the project publicly visible,
+you must move the code-signing private key
+to a highly secure (preferably non-networked) host,
+and delete it from the server host.
+<li> Create a MySQL database for this project,
+named (BOINC_USER_NAME)_(project-name).
+<li> Insert initial records in the project, platform, user, and app tables.
+<li> Copy the server programs (cgi, feeder, file_upload_handler)
+from the source directory to the project/cgi directory.
+<li> Generate the configuration file (config.xml) used by
+the server programs.
+<li> Copy the user and administrative PHP files to the
+project directories html_user and html_ops.
+<li> Create a file "db_name" in project/html_user and project/html_ops
+so that the project web sites access the right database.
+<li> Macro-process html_user/index.html to insert the correct scheduler URL.
+<li> Create symbolic links (with the project name)
+from the main HTML and CGI directories to the project directory.
+</ul>
+
+<p>
+At this point you hopefully have a functioning BOINC server,
+but it has no applications or work to distribute.
+The remaining steps to make a public project include:
+<ul>
+<li> Develop, debug and test your application.
+<li> Develop back-end systems for generating work and processing results.
+<li> Using the "add" utility, add application versions to the BOINC database.
+<li> Develop your web site.
+</ul>