The master URL

Each project is publicly identified by a master URL. The page at this URL has two functions.

• It is the home page of the project; when viewed in a browser it describes the project and contains links for downloading the BOINC client.
• It contains XML elements of the form

  <scheduler>http://host.domain.edu/cgi/scheduler</scheduler>
  <scheduler>http://host2.domain.edu/cgi/scheduler</scheduler>
  

  that give the URLs of the project's scheduling servers. These tags can be embedded within HTML comments. The BOINC client reads and parses the master page to locate scheduling servers. If at any point it is unable to connect to any scheduling server for a project, it rereads the master page. This mechanism lets a project move or add scheduling servers.

Some ISPs remove HTML comments from downloaded pages. To avoid problems with that, an alternative syntax is allowed:

<link rel="boinc_scheduler" href="http://host.domain.edu/cgi/scheduler">

You should still use the <scheduler> format too, since older clients won't parse this new syntax.

The make_project script creates a master page in project/html/user/index.php. This file includes the file 'schedulers.txt', which contains the list of <scheduler> (and <link>) elements.

Choosing a project URL

It's recommended that projects choose master URLs that allow the server to change location. For example, even if you're still starting with a test project, don't use an IP address in the URL; use an actual hostname. Even having the university name as part of the hostname may be a bad idea. In December 2007, Docking@Home moved from the University of Texas at El Paso to the University of Delaware, and had to change their URL from docking.utep.edu to docking.cis.udel.edu. This required their volunteers to attach to the new project, and some volunteers were lost. Thus, the best way is having a hostname just for that project. ​Good URLs don't change.

Even having multiple projects in the same hostname, like http://boinc.example.org/project1/ and http://boinc.example.org/project2/ may be problematic if you eventually decide you want to move project2 to a different server. It's best to have project1.example.org and project2.example.org so they can (now or in the future) have different IP addresses.

How to change a project URL

All that said, here is how you change a project URL:

1. Pick a good new URL according to the above recommendations, so that you will never need to change it again.
2. If the project was ever public, post news to let users know the URL will change.
3. If any BOINC stats website carries your project, let the site admins know about the URL change.
4. If you have any tasks in progress or waiting to be sent, it's recommended you wait until they are all done before changing the URL. And/or abort the unsent tasks. You could edit the database to fix URLs for input files, to make the unsent workunits work once the URL is changed; but it's probably more trouble than it's worth, and won't help with workunits that people already have in their client queue.
5. Stop the project. Take the website down too.
6. Replace the URL everywhere in config.xml
7. Replace the scheduler URL in html/users/schedulers.txt. Its prefix should match the URL in <cgi_url> in config.xml.
8. If you have project-wide files, like logos for the simple GUI, replace download URLs in project_files.xml
9. Delete everything in html/cache, since cached pages may have links to the old URL, and users would get broken links for an hour or so. Don't delete the cache folder itself.

    rm -rf html/cache/*
   

10. Either create new application versions, or update the app_version table to have the new URLs:

     UPDATE app_version SET xml_doc = REPLACE(xml_doc, "http://old.example.com/", "http://new.example.org/");
    

11. If you have forums enabled, you may want to do a similar replacement on forum contents, in case users posted links to their computers or similar.
12. Start the project, send some test workunits, and make sure everything is working.