Marla - The Websites of Aaron Faanes

Marla contains the web configuration and content for each of my websites. Each
website can be found under its directory, with the following organization:

example.com/            Root for this website
example.com/httpd/      Apache configuration
example.com/static/     Static content: css, js, etc.

This organization will be created automatically by bin/make-site. You should use
that command when starting from scratch. make-site should construct a relatively
complete framework for a new site. Marla will indicate if any manual
intervention is required.

While Marla intends to be a mostly-automated tool for creating and deploying
websites, I haven't intended it to be used outside my own setup. As a result,
any intrepid people who wish to steal it are welcome to do so, but do so at
their own risk.

Each website will be built using make and installed using make install.
Installation via RPM is also supported. By convention, each website will become
a new subpackage of marla, such as marla-example-com.

## Making a new website

1. scaf marla www.example.com
2. cd www.example.com
3. ... Setup httpd.conf, CGI, etc ...

## Installing

Marla is designed to support incremental roll-out of web applications. Generally
speaking, you should run marla from within a chroot.

### Configuration

One problem often encountered when testing websites is how to deal with DNS
resolution. Marla solves this problem by separating configuration into a 'local'
profile and a 'linode' profile.

The 'local' profile will map each of your websites to a different port, so
website-1 will be localhost:8080, website-2 will be localhost:8081 and so forth.

    ./configure local

The 'linode' profile behaves as you'd expect on a production server: each
website is mapped to its proper DNS name.

    ./configure linode

### Profile Variables

* _LISTEN_BASE_ sets the port offset when configuring local servers. During
testing, each website will be given a different port starting from this
variable.
* _PORT_ sets the port for a production website. In this case, domain names will
be used and all virtual hosts will use the same port and IP address.
* _IP_ is the IP address used for each virtual host.

### Testing and Deployment

Website development needs to be tested, and usually, testing on a live
environment is hazardous and unnecessary. Marla supports fine-grained deployment
to allow testing at various stages of deployment.

#### Dry-Run Deployment

Marla relies extensively on autogenerated files and substitutions. While these
methods ease the cost of development, they also increase the complexity and
likelihood of errors. If you've made changes to the httpd configuration or the
build system, you should test these changes by performing a dry-run deployment.

Dry-run deployment is done by installing Marla to a temporary directory. The
directory structure will be entirely created at this point, but there will be no
execution capability. This allows you to quickly investigate whether your
changes were successful without breaking a live server or corrupting a chroot.

    make install DESTDIR=/tmp/marla/1

### Chrooted Deployment

Once you're satisfied with your dry-run deployment (or if you're confident a dry
run is not necessary), you'll want to deploy Marla to a real Apache server.

#### Chroots

Marla provides scripts to create and manage a chroot capable of running a
website. It is possible to deploy directly without using a chroot, there's no
need to do so: the chroots offer reliabilty, security, and flexibility in how
you deploy, all without endangering the underlying system. I will assume you're
using a chroot when you're deploying with Marla.

#### RPM

Marla creates RPM files so that you can install, upgrade, and remove Marla using
the safety and reliability of a package manager. You should prefer installing
via RPM whenever possible. Installation using make directly is possible, but not
recommended. Similar to the chroot discussion, I will assume you're using RPM or
Yum to install Marla (unless you're doing a dry-run deployment).

While Marla uses RPM for installation, you should not use RPM for site content.
Marla should only install backend-level components (e.g, scripts,
configuration). Content such as flatfiles, images, and other media should be
placed in /srv. Marla does not manage these files directly, so it's up to you
how you want to deploy this content. Some combination of a version-control
system, a build tool, and rsync will likely suffice.

### Process

When you're ready to deploy, you'll go through the following process. The
commands may differ slightly depending on if you're using an installed version
of Marla's tools or working from the source repo.

	# Build the Yum repo we use
	$ cd ~/src/repomaker
	$ make package
	$ make deploy

	# Create a new chroot. This will take some time.
	$ marla-chroot-create test1

	# Install the configuration of marla you want.
	$ marla-chroot-yum test1 install marla-local-*

	# Run apache
	$ marla-chroot-run test1 /sbin/apachectl start

### Undeploying

When you're ready to take the server down, go through the following process:

	# Unmount all partitions for this chroot and shut down Apache
	$ marla-chroot-disable test1

	# Delete the chroot
	$ rm -fr /media/chroot/marla/test1

### Live Deployment

The process of deploying Marla to a production website is almost identical to
how it's deployed to a testing website. The only difference is the installed
configuration; you'll want to use the configuration that has the correct IP
address for your websites.

There are a few extra steps to finalize a production site: First, you'll need to
set up any authorization schemes you're using:  password files for server-level
authentication, SSL certificates and keys, and so forth. Since it would be
dangeorus to have these credentials managed automatically, Marla does not
attempt to set them up. If you forget to install any of these, Apache should
remind you accordingly.

vim: set tw=80 et! :