Detailed installation instructions

README.textile

@@ -56,22 +56,61 @@ h2. What You'll Need
 # A wildcard SSL certificate. I bought one. You could self-sign if you wanna save money.
 # A "Tarsnap":http://www.tarsnap.com account with some credit in it. You could comment this out if you want to use a different backup service. I pay for backups at Linode in addition to the Tarsnap nightlies because you can never be too sure.
 
-h2. Manual Steps
+h2. Installation
 
-This does a lot for you automatically but there's still some stuff you have to do by hand.
+h3. 1. Get a wildcard SSL certificate
 
-# Create a user account for Ansible to do its thing through. This account should be set up for passwordless sudo.
-# Put your Tarsnap key in @roles/common/files/root_tarsnap.key@.
-# Put your SSL certificate's components in the respective files that start with @wildcard_ca@ in @roles/common/files@, and a combined version in @roles/ircbouncer/files/etc_ssl_znc-combined.pem@.
-# Set up SPF and reverse DNS "as per the inspirational post":http://sealedabstract.com/code/nsa-proof-your-e-mail-in-2-hours/. Make sure to validate that it's all working, for example by sending an email to <a href="mailto:check-auth@verifier.port25.com">check-auth@verifier.port25.com</a> and reviewing the report that will be emailed back to you.
-# Sign in to the ZNC web interface and set things up to your liking.
+Create a private key and a certificate signing request (CSR):
 
-Now, the time-consuming part: grep through the files for the string @TODO@ and replace as necessary. You'll probably want to check out all the files in the respective @vars/@ sub-directories in each playbook directory.
+bc. openssl req -nodes -newkey rsa:2048 -keyout roles/common/files/wildcard_private.key -out mycert.csr
+
+Purchase a wildcard cert from a certificate authority, such as "Positive SSL":https://positivessl.com or "AlphaSSL":https://www.alphassl.com. You will provide them with the contents of your CSR, and in return they will give you your signed public certificate. Place the certificate in @roles/common/files/wildcard_public_cert.crt@.
+
+Download your certificate authority's combined cert to @roles/common/files/wildcard_ca.pem@. You can also download the intermediate and root certificates separately and concatenate them together in that order.
+
+Lastly, test your certificates using the @security@ program on Mac OS X:
+
+bc. security verify-cert -L -p ssl -s example.com -c roles/common/files/wildcard_public_cert.crt -c roles/common/files/wildcard_ca.pem
+...certificate verification successful.
+
+h3. 2. Get a Tarsnap machine key
+
+If you haven't already, "download and install tarsnap":https://www.tarsnap.com/download.html, or use @brew install tarsnap@ if you use "Homebrew":http://brew.sh.
+
+Create a new machine key for your server:
+
+bc. tarsnap-keygen --keyfile roles/common/files/root_tarsnap.key --user me@example.com --machine example.com
+
+h3. 3. Prep the server
+
+For goodness sake, change the root password:
+
+bc. passwd
+
+Create a user account for Ansible to do its thing through:
+
+bc. useradd deploy
+passwd deploy
+mkdir /home/deploy
 
-h2. Running It
+Authorize your ssh key if you want passwordless ssh login (optional):
+
+bc. mkdir /home/deploy/.ssh
+chmod 700 /home/deploy/.ssh
+nano /home/deploy/.ssh/authorized_keys
+chmod 400 /home/deploy/.ssh/authorized_keys
+chown deploy:deploy /home/deploy -R
+
+This account should be set up for passwordless sudo. Use @visudo@ and add this line:
+
+bc. deploy  ALL=(ALL) NOPASSWD: ALL
+
+h3. 4. Run the ansible scripts
 
 First, make sure you've "got Ansible installed":http://ansibleworks.com/docs/gettingstarted.html#getting-ansible.
 
+Now, the time-consuming part: grep through the files for the string @TODO@ and replace as necessary. You'll probably want to check out all the files in the respective @vars/@ sub-directories in each playbook directory.
+
 To run the whole dang thing:
 
 bc. ansible-playbook -i ./hosts site.yml
@@ -82,6 +121,19 @@ bc. ansible-playbook -i ./hosts --tags=ferm site.yml
 
 You might find that it fails at one point or another. This is probably because something needs to be done manually, usually because there's no good way of automating it. Fortunately, all the tasks are clearly named so you should be able to find out where it stopped. I've tried to add comments where manual intervention is necessary. OpenVPN in particular requires a bunch of manual command line stuff to get running.
 
+h3. 5. Set up DNS
+
+If you've just bought a new domain name, point it at "Linode's DNS Manager":https://library.linode.com/dns-manager or similar. Most VPS services (and even some domain registrars) offer a managed DNS service that you can use for this at no charge. If you're using an existing domain that's already managed elsewhere, you can probably just modify a few records.
+
+Create an @A@ record for @example.com@ as well as @mail.example.com@ which points to your server IP. Create an @MX@ record for @example.com@ which assigns @mail.example.com@ as the domain's mail server.
+
+Set up SPF and reverse DNS "as per the inspirational post":http://sealedabstract.com/code/nsa-proof-your-e-mail-in-2-hours/. Make sure to validate that it's all working, for example by sending an email to <a href="mailto:check-auth@verifier.port25.com">check-auth@verifier.port25.com</a> and reviewing the report that will be emailed back to you.
+
+h3. 6. Miscellaneous Configuration
+
+Sign in to the ZNC web interface and set things up to your liking.
+
+
 h2. How I Use It
 
 First, I moved all my email off Google with "larch":https://github.com/rgrove/larch/. It worked like a charm. Calendars and contacts were even easier: just export and then import the standard formats with your clients of choice; no issues with Calendar.app and Contacts.app.

site.yml

@@ -2,7 +2,7 @@
 # This is the top-level playbook that defines our entire infrastructure.
 
 - hosts: all
-  user: TODO
+  user: deploy
   sudo: True
   gather_facts: False