Local Filestructure

The quarkcat user

We create a system user called quarkcat to maintain consistency among developers.

On a Linux system, create this user as

$ sudo adduser --system --group quarkcat

This will add quarkcat as a user and a group and will create its home directory /home/quarkcat/ where we will keep e-Lab development files. The --system flag tells the OS this user isn't a real user and won't have a password or login.

Local files

Once ~quarkcat/ is created, create subdirectories

  ~quarkcat/sw/
  ~quarkcat/sw/i2u2svn/

[with, e.g., $ sudo -u quarkcat mkdir -p sw/i2u2svn/ ]. The sw/ directory is where we store e-Labs-related software; the i2u2svn/ directory will contain a local working copy of the e-Labs source code SVN repository.

You will also need the sw/local-settings/ and and a sw/vds/ directories and the files they contain, in addition to the four scripts

.vdsrc
setenv.sh
deploy-from-svn
internal-deploy-from-svn

that are kept in the ~quarkcat/ directory. See below for descriptions of what these things are. You can obtain copies of these directories from one of the other developers or from one of the server VMs i2u2-dev or i2u2-prod.

Getting local files from the VMs

To copy the files you need from (for example) i2u2-dev to your machine, you can use tar and scp as shown:

# On the remote VM (i2u2-dev)
$ cd ~quarkcat/
$ sudo -u $USER tar -chzf $HOME/swdirs.tar.gz .vdsrc setenv.sh deploy-from-svn internal-deploy-from-svn sw/local-settings/ sw/vds/

The vds/ folder is a symlink to vds-1.4.8/, a setup originally intended to make it easy to switch VDS versions by switching the symlink. As of 2021, VDS development has been long since abandoned, so you don't need to worry about versioning for local development. The -h flag to the tar command will make tar grab the symlinked content, and not just the symlink itself.

Pull the swdirs.tar.gz archive (or whatever you named it) to your machine, inserting your username from the remote VM as needed:

# On your local machine
$ cd ~quarkcat/
$ sudo scp {remote username}@i2u2-dev.crc.nd.edu:/home/{remote username}/swdirs.tar.gz /home/quarkcat
$ sudo tar --same-owner -xzf swdirs.tar.gz 

The original tar recorded quarkcat's ownership of the archived files; using the --same-owner flag while extracting them keeps them quarkcat's instead of root's so that you don't have to mess with chown or chmod.

Tomcat symlink

After Tomcat is installed, which it should already be if you've been following this guide in order, you'll create a directory symlink within ~quarkcat/sw/ to the Tomcat installation so that "live" website files are accessible within the ~quarkcat/ directory.

$ ln -s /var/lib/tomcat{X}/ ~quarkcat/sw/tomcat

(the command shown is for Ubuntu, insert the appropriate version of Tomcat). The -s flag creates a "soft" symlink, which is the only kind possible for directories. The first argument is the source filepath, while the second is the new symlink that's created. (Note that the command won't work if the second argument filepath ends in a /. A symlink is a file, not a directory, even though in this case it's a file that represents a directory).

If your Tomcat installed to a different location than /var/lib/tomcat{X}/, the important thing is that the ~quarkcat/sw/tomcat/ symlink points to the directory within which /webapps/ROOT/ resides. It might be called tomcat/ or tomcat{X}/ or apache-tomcat-(version)/ depending on your system.

Finished product

By the time you're finished, the ~quarkcat/ directory should have the following structure:

~quarkcat/
    |-- deploy-from-svn
    |-- internal-deploy-from-svn
    |-- setenv.sh
    |-- sw/
    |   |-- i2u2svn/
    |   |-- local-settings/
    |   |-- tomcat -> /var/lib/tomcat/
    |   |-- vds/
    |-- .vdsrc

sw/ presumably stands for "software," referring to the website software, all of which will be contained within it.

local-settings/ will contain configuration files unique to your local environment - the settings that make your development machine different from the VMs the code is normally deployed on, so that we can deploy the same code to different machines just by changing a few config files.

vds/ stands for "Virtual Data Systems." It's something some of the original e-Lab authors came up with (Mike Wilde, I think), and it's unique to ELabs/QuarkNet as far as I can tell. I don't understand it. You don't need to, either. Probably.

i2u2svn/ is where quarkcat's working copy of the source code repository will be written. NB: This is different from your personal working copy, which should be outside of the quarkcat/ folder!

tomcat/ is a directory symlink to wherever you install Tomcat on your system, as described later in the Tomcat installation page. This symlink allows us to have both the repository files in i2u2svn/ and the live site files in tomcat/webapps/ under the same ~quarkcat/ umbrella folder. You don't need to create the tomcat/ directory at this time, because you'll do that when you make the symlink. It's included here for completeness.

The contents of local-settings/ and vds/ will be included in the archive (vds/ in particular is extensive; take a look at it with tree to see). The contents of tomcat/ are determined by the Tomcat installation, and the contents of i2u2svn/ will be created when the deployment scripts copy the repository to it.

-- Main.JoelG - 2016-07-29

Comments