summaryrefslogtreecommitdiff
path: root/docs/en/tutorials/single-node-email.html
blob: d3372f9100c69afd5a5f1c5fb44b1e60c935bec6 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
<!DOCTYPE html>
<html lang='en'>
<head>
<title>
Quick email - LEAP Platform Documentation
</title>
<meta content='width=device-width, initial-scale=1.0' name='viewport'>
<meta charset='UTF-8'>
<base href="" />
<style>
  body {
    background: #444;
    display: flex;
    flex-direction: row;
    padding: 10px;
    margin: 0px;
  }
  #sidebar {
    flex: 0 0 250px;
    background: white;
    margin-right: 10px;
    padding: 20px;
  }
  #sidebar ul {
    list-style-type: none;
    padding-left: 0px;
    margin: 0;
  }
  #sidebar li { padding: 4px }
  #sidebar li a { text-decoration: none }
  #sidebar li.active { background: #444 }
  #sidebar li.active a { color: white }
  #sidebar li.level1 { padding-left: 20px }
  #sidebar li.level2 { padding-left: 40px }
  #main {
    flex: 1 1 auto;
    background: white;
    padding: 20px;
  }
  #title-box {
    padding-bottom: 20px;
    border-bottom: 5px solid #eee;
  }
  #title-box h1 {
    margin-top: 0px;
  }
  pre {
    padding: 10px;
    background: #eef;
  }
  code {
    background: #eef;
  }
  table {border-collapse: collapse}
  table td {
    border: 1px solid #ccc;
    padding: 4px;
    vertical-align: top;
  }
</style>
</head>
<body>
<div id='sidebar'>
<ul>
<li class=''>
<a href='../../index.html'>Home</a>
</li>
<li class=' level0'>
<a class='' href='../guide.html'>Guide</a>
</li>
<li class='semi-active level0'>
<a class='' href='../tutorials.html'>Tutorials</a>
</li>
<li class=' level1'>
<a class='' href='quick-start.html'>Quick Start Tutorial</a>
</li>
<li class=' level1'>
<a class='' href='single-node-vpn.html'>Quick VPN</a>
</li>
<li class='active level1'>
<a class='' href='single-node-email.html'>Quick email</a>
</li>
<li class=' level1'>
<a class='' href='vagrant.html'>Vagrant</a>
</li>
<li class=' level0'>
<a class='' href='../services.html'>Services</a>
</li>
<li class=' level0'>
<a class='' href='../upgrading.html'>Upgrading</a>
</li>
<li class=' level0'>
<a class='' href='../troubleshooting.html'>Troubleshooting</a>
</li>
<li class=' level0'>
<a class='' href='../details.html'>Details</a>
</li>
</ul>
</div>
<div id='main'>
<div id='title-box'>
<h1>Single node email tutorial</h1>

<div id='summary'>Tutorial for setting up a simple email provider.</div>
</div>
<div id='content-box'>
<div id="TOC"><ol>
  <li>
    <a href="single-node-email/index.html#our-goal">Our goal</a>
  </li>
  <li>
    <a href="single-node-email/index.html#add-email-services-to-the-node">Add email services to the node</a>
  </li>
  <li>
    <a href="single-node-email/index.html#deploy-to-the-node">Deploy to the node</a>
  </li>
  <li>
    <a href="single-node-email/index.html#setup-dns">Setup DNS</a>
  </li>
  <li>
    <a href="single-node-email/index.html#test-it-out">Test it out</a>
  </li>
</ol></div>

<p>This tutorial walks you through the initial process of creating and deploying a minimal email service provider. Please first complete the <a href="quick-start.html">Quick Start Tutorial</a>. This tutorial will pick up where that one left off.</p>

<h2><a name="our-goal"></a>Our goal</h2>

<p>We are going to create a minimal LEAP provider offering email service.</p>

<p>Our goal is something like this:</p>

<pre><code>$ leap list
    NODES       SERVICES                       TAGS
    wildebeest  couchdb, mx, soledad, webapp
</code></pre>

<p>Where &lsquo;wildebeest&rsquo; is whatever name you chose for your node in the <a href="quick-start.html">Quick Start Tutorial</a>.</p>

<h2><a name="add-email-services-to-the-node"></a>Add email services to the node</h2>

<p>In order to add <a href="../services.html">services</a> to a node, edit the node&rsquo;s JSON configuration file.</p>

<p>In our example, we would edit <code>nodes/wildebeest.json</code>:</p>

<pre><code>{
  "ip_address": "XXX.XXX.XXX.XXX",
  "services": ["couchdb", "webapp", "mx", "soledad"]
}
</code></pre>

<p>Where &ldquo;XXX.XXX.XXX.XXX&rdquo; should be replaced by your IP provider.</p>

<p>Here, we added <code>mx</code> and <code>soledad</code> to the node&rsquo;s <code>services</code> list. Briefly:</p>

<ul>
<li><strong>mx</strong>: nodes with the <strong>mx</strong> service will run postfix mail transfer agent, and are able to receive and relay email on behalf of your domain. You can have as many as you want, spread out over as many nodes as you want.</li>
<li><strong>soledad</strong>: nodes with <strong>soledad</strong> service run the server-side daemon that allows the client to synchronize a user&rsquo;s personal data store among their devices. Currently, <strong>soledad</strong> only runs on nodes that are also <strong>couchdb</strong> nodes.</li>
</ul>


<p>For more details, see the <a href="../services.html">Services</a> overview, or the individual pages for the <a href="../services/mx.html">mx</a> and <a href="../services/soledad.html">soledad</a> services.</p>

<h2><a name="deploy-to-the-node"></a>Deploy to the node</h2>

<p>Now you should deploy to your node.</p>

<pre><code>workstation$ leap deploy
</code></pre>

<h2><a name="setup-dns"></a>Setup DNS</h2>

<p>There are several important DNS entries that all email providers should have:</p>

<ul>
<li>SPF (Sender Policy Framework): With SPF, an email provider advertises in their DNS which servers should be allowed to relay email on behalf of your domain.</li>
<li>DKIM (DomainKey Identified Mail): With DKIM, an email provider is able to vouch for the validity of certain headers in outgoing mail, allowing the receiving provider to have more confidence in these values when processing the message for spam or abuse.</li>
</ul>


<p>In order to take advantage of SPF and DKIM, run this command:</p>

<pre><code>workstation$ leap compile zone
</code></pre>

<p>Then take the output of that command and merge it with the DNS zone file for your domain.</p>

<p>CAUTION: the output of <code>leap compile zone</code> is not a complete zone file since it is missing a serial number. You will need to manually merge it with your existing zone file.</p>

<h2><a name="test-it-out"></a>Test it out</h2>

<p>First, run:</p>

<pre><code>workstation# leap test
</code></pre>

<p>Then fire up the bitmask client, register a new user with your provider, and try sending and receiving email.</p>

</div>
</div>
</body>
</html>