Browse Source

Detailed installation instructions

Luke Cyca 11 years ago
parent
commit
cf3961b654
2 changed files with 62 additions and 10 deletions
  1. 61
    9
      README.textile
  2. 1
    1
      site.yml

+ 61
- 9
README.textile View File

@@ -56,22 +56,61 @@ h2. What You'll Need
56 56
 # A wildcard SSL certificate. I bought one. You could self-sign if you wanna save money.
57 57
 # 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.
58 58
 
59
-h2. Manual Steps
59
+h2. Installation
60 60
 
61
-This does a lot for you automatically but there's still some stuff you have to do by hand.
61
+h3. 1. Get a wildcard SSL certificate
62 62
 
63
-# Create a user account for Ansible to do its thing through. This account should be set up for passwordless sudo.
64
-# Put your Tarsnap key in @roles/common/files/root_tarsnap.key@.
65
-# 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@.
66
-# 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.
67
-# Sign in to the ZNC web interface and set things up to your liking.
63
+Create a private key and a certificate signing request (CSR):
68 64
 
69
-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.
65
+bc. openssl req -nodes -newkey rsa:2048 -keyout roles/common/files/wildcard_private.key -out mycert.csr
66
+
67
+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@.
68
+
69
+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.
70
+
71
+Lastly, test your certificates using the @security@ program on Mac OS X:
72
+
73
+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
74
+...certificate verification successful.
75
+
76
+h3. 2. Get a Tarsnap machine key
77
+
78
+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.
79
+
80
+Create a new machine key for your server:
81
+
82
+bc. tarsnap-keygen --keyfile roles/common/files/root_tarsnap.key --user me@example.com --machine example.com
83
+
84
+h3. 3. Prep the server
85
+
86
+For goodness sake, change the root password:
87
+
88
+bc. passwd
89
+
90
+Create a user account for Ansible to do its thing through:
91
+
92
+bc. useradd deploy
93
+passwd deploy
94
+mkdir /home/deploy
70 95
 
71
-h2. Running It
96
+Authorize your ssh key if you want passwordless ssh login (optional):
97
+
98
+bc. mkdir /home/deploy/.ssh
99
+chmod 700 /home/deploy/.ssh
100
+nano /home/deploy/.ssh/authorized_keys
101
+chmod 400 /home/deploy/.ssh/authorized_keys
102
+chown deploy:deploy /home/deploy -R
103
+
104
+This account should be set up for passwordless sudo. Use @visudo@ and add this line:
105
+
106
+bc. deploy  ALL=(ALL) NOPASSWD: ALL
107
+
108
+h3. 4. Run the ansible scripts
72 109
 
73 110
 First, make sure you've "got Ansible installed":http://ansibleworks.com/docs/gettingstarted.html#getting-ansible.
74 111
 
112
+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.
113
+
75 114
 To run the whole dang thing:
76 115
 
77 116
 bc. ansible-playbook -i ./hosts site.yml
@@ -82,6 +121,19 @@ bc. ansible-playbook -i ./hosts --tags=ferm site.yml
82 121
 
83 122
 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.
84 123
 
124
+h3. 5. Set up DNS
125
+
126
+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.
127
+
128
+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.
129
+
130
+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.
131
+
132
+h3. 6. Miscellaneous Configuration
133
+
134
+Sign in to the ZNC web interface and set things up to your liking.
135
+
136
+
85 137
 h2. How I Use It
86 138
 
87 139
 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.

+ 1
- 1
site.yml View File

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

Loading…
Cancel
Save