A strategy for becoming a Sidai-style ARK site

What is a sane overall strategy for doing the full Sidai-style ARK thing? This document addresses that. (You don't have to do ``full thing'', of course; see ways to use ARK...)

The watchword is 'grow slowly'. Details of exactly how to do all of these things are provided elsewhere (we hope).

Boning up

1. Read the ``blessed names'' guide, so you'll know what to call disks, partitions, etc. You can decide differently, of course, but it's worth understanding why we suggest what we do.

2. The steps in the `sample1'-style try-it-out guide are basically right, except you'll now use ``real'' directories for stuff, rather than dark corners of your home directory. If you haven't seen that doc yet, it may be faintly instructive.

3. If the ARK objects guide makes no sense to you, you're going to have trouble. Please ask about anything that is unclear!

4. You will eventually need to consult the ARK configuration language guide, so you can write your own ARK .xml files.

   The guide still has big holes in it, so please speak up if you are about to fall into one.

5. A really good way to make progress is simply to poke around into how another team as done things! Various teams' real stuff is downloadable).

   The `verilab2' (better) and `glasli1' (older) teams are real, full-blown Sidai-style sites, and may therefore be a particularly useful examples, given what you're trying to do.

   We would caution against blindly copying `verilab2' or `glasli1' stuff. There are various root-wielding things going on which are customized to the site, and which might cause untold misery if mindlessly duplicated at your site.

Start doing ARK for real!

Note: you will benefit greatly from peeking at another real team's files, e.g. `verilab2'. That's what they're there for.

1. You may wish to check all of the ARK code at hand into a local CVS repository. (You probably will if that's your style; and probably won't otherwise. Please plan to keep your own team's stuff in CVS, or equivalent.)

2. We'll assume you are starting with just one host (call it host1), which we will pretend is a SPARC Solaris box.

3. If you are really serious about the ARK notion of knowing-where-all-the-bits-came-from, you will install a raw OS on host1 as your first step! (Not that anally-retentive? -- just plough on!)

4. Before you can do much of anything with host1, you will need to install the pre-requisite tools. (You may have already done this in a try-ark experiment.)

   A typical scenario would be to end up with GCC, Python, and maybe Perl, installed in /usr/local.

5. You need set up the host-specific ARK directories on host1. Details instructions are elsewhere; they reflect a choice of pathnames which Sidai blessed names -- you may use other names, if you wish.

6. You will also need a few site-wide (i.e. shared by all hosts) ARK directories. Detailed instructions are elsewhere.

7. Start setting up your site team, which we will call wondrous herein. Thus, you need a directory $ARK_SRC/wondrous, to sit alongside $ARK_SRC/sidai, and so on.

8. Create a $ARK_SRC/wondrous/team.xml with basic details about your team. A full description of that file, including points to note, is elsewhere.

9. Time to double-check your wondrous/package/ALL.xml... much detail about this file is elsewhere.

   Mostly: be sure that the pathnames in the file match what you chose/specified in the previous steps.

10. You will now need to specify host1) in ARK-speak. You will be creating a file $ARK_SRC/wondrous/host/host1.xml.

    An ARK host gets much of its information from its prototypes. One way forward is to `borrow' from a similar set of prototypes. As host1 is a Sun, and (as it happens) hermione out of the `verilab2' team is a Sun, why not `borrow' its prototypes to get started?

    So, you might copy over from verilab2/host/: ALL.xml, sparc-solaris.xml, sparc-solaris8.xml, sun-ultra60.xml, and hermione.xml.

    Make the needed changes: if host1 is really a Netra t1, then rename sun-ultra60.xml to sun-netra-t1.xml and (of course) hermione.xml to host1.xml. Edit these files, making the obvious network address changes, etc.

11. Time to double-check your wondrous/host/ALL.xml... much detail about this file is elsewhere.

    As it says, much of the file is just saying where particular tools live on your system; most of the definitions use `macros' defined in your team.xml. Just be sure that ALL.xml isn't `lying'.

12. Have you got your ARK_PROFILE environment variable set? If not, do so (setenv ARK_PROFILE ~/.ark_profile), and creating that file appropriately (details elsewhere).

13. You may recall from sample1's try-ark that the first thing it does is ARKishly build/install ARK itself, as well as some external tools that are fairly deeply embedded in the Sidai way of doing things (e.g. gzip). Do the same here:

    cd $ARK_SRC/ARK/arkbase
    
    # ARK itself:
    ./arkcmd package reveal --verbose arkbase
    

14. The next thing try-ark does is 'reveal' the ALL proto-package using the just-installed ARK (we assume it is now visible as /our/bin/tar), i.e.

    /our/bin/ark package reveal --verbose ALL
    

    If you look in the `sample1' package/ directory, you'll see what ALL refers to: arkbase (already done), ark-prereq-utils, ark-site-gen (already done) gzip--1.3.5, rsync--2.4.7, and coreutils--5.2.1.

    We'd suggest you set up your package directory so that `ALL' refers to these packages...

    Package	At least version...	Comments
    ark-prereq-utils	-
    gcc	3.2	Or live with what you have
    gzip	1.3.x	Or live with what you have
    rsync	2.5.7	Current at time of writing
    GNU tar	1.13.25	Yes, it's better
    texinfo	4.6	GCC wants to see a modern Texinfo
    coreutils	-	md5sum is all we're after

    ... and then you do the same:

    /our/bin/ark package reveal --verbose ALL
    

15. Once all of those tools are built, be sure that your host/ALL.xml defines the ARK-built ones as the ones you want.

16. If you've made it this far (hooray!), you should be able to build any of a large number of open-source packages, probably by peeking at what the `verilab2' or `glasli1' teams have done, and doing the same.

    Perhaps do at least one or two, just to be sure you've got the hang of things.

17. But before racing ahead... take care of the `multi-platform' aspect of all of this (assuming it applies in your case).

    Add one host of each additional type--yes, more files in your host/ directory. So, if you've got Linux and AIX boxes as well as Solaris, add two more hosts. Add suitable prototypes.

    Now go back and build the same packages for these new hosts. If you type ark package reveal ALL, it should simply pick up where it left off and finish the job...

18. You are at the point where you could ``fill out'' your (multi-platform) ARK setup with many, many packages.

    Don't :-) First, set up a CVS repository for your site's stuff, and check in what you've done so far. It's real after this...

19. While you're at it, set up a second ``team'' for yourself, wondrous-private. This is the team that will hold security-sensitive stuff, e.g. related to passwords, groups, and so on. (Small, but important.)

    Whereas your goal should be to make the wondrous team's stuff visible to (some chunk of) the world, your goal should be the opposite for wondrous-private. Its contents should be version-controlled, but whatever you do, don't set it up for anonymous access :-)

Fleshing out your set of packages

Planning how to structure your sysadmin work

The variables that need juggling at this point are:

• The `scale' of your site (number of hosts, etc.)
• The `complexity' of your setup -- do you have many hosts that are cookie-cutter copies, or do you have hosts doing a whole bunch of different complex tasks, or what?
• The `delicacy' of your setup -- do you have never-never-never-must-go-down production machines, or a looser what's-a-reboot-among-friends site?
• The number of sysadmins actively doing concurrent development on your ARK setup.

Simple case: If you are a solo sysadmin at a small-ish site (say, 20 hosts) and with nothing too precious about your site's hosts, then you can check out one `workspace' from CVS, and do everything from that. In other words, your development `workspace' (where you sit and hack ARK day to day) and your production `workspace' (what drives the configuration of all of your machines) are one and the same.

The core ARK developers do this simple kind of thing, and it works fine. A little chaos never hurt anyone :-)

Complex case: You have several sysadmins hacking on ARK stuff regularly, and you have Good Reasons to maintain clear blue water between production and development machines. In this case:

• You will definitely have a configuration management plan (in the software sense -- see Brad Appleton's comprehensive site).

  We'll assume the common arrangement: development happens at the `HEAD', and releases branch off of that. Production machines operate off a stable branch; test machines off of a test branch, etc.

• This suggests three categories of hosts: production machines (off a stable branch), test machines (a small collection -- one per flavor?) with which to test releases before they go into production (become stable), and developer machines (again, ideally, more than one apiece), which will operate against developer's individual workspaces as they develop ARK solutions.

• Development might then proceed as follows:
  1. Sysadmins work "at the HEAD" to develop a set of `features' for the production machines, testing them on their own developer machines.

  2. Once the head version believed to be usable, a test branch would be started, and the work would be tested on the test machines. These machines would see the ARK stuff in a `checkouts-only' workspace.

  3. Fairly serious test criteria would presumably be used to decide that the test branch was worthy of use on the production machines. This might include, for example: ``The whole test-machine network can be rebuilt from raw with a single command.''

  4. Once satisfactorily robust, the test branch would become a stable branch. The `checkouts-only' workspace from which production machines see the ARK stuff would be updated to see the new production (stable) branch.

  5. Depending on the changes in the new release, particular rollover/conversion programs might be run.