Skip to content

Instantly share code, notes, and snippets.

@JoshData
Created April 27, 2015 22:48
Show Gist options
  • Save JoshData/48db3364802deac4348f to your computer and use it in GitHub Desktop.
Save JoshData/48db3364802deac4348f to your computer and use it in GitHub Desktop.
miab video script draft
Hello and welcome to the Mail-in-a-Box setup guide. Mail-in-a-Box
helps you take control of your email with an easy to deploy mail
server in a box. This video tutorial will walk you through the same
instructions that are found in the setup guide on the Mail-in-a-Box
website. This will take you about two hours.
Let’s say I want a new email address for myself, say, [email protected].
I’m going to need a domain name --- that’s joshmail.xyz. And a server.
Mail-in-a-Box configures that servers to that it provides mail server
functionality, including support for mobile devices, webmail, spam
filter, and other protocols needed for mail delivery.
Please go through the pre-flight checklist on the website. Note the
cost. And if you have a website or a web server already, or if you
want to tinker with the system after setting it up, please consult the
website.
Your first task is to choose a domain name. The part after the @ sign
in an email address is a domain name, and you’ll have to buy one that
you want, if it is available. You can buy whatever domain name you
like, except t at the every domain name ends in one of about 900 Top
Level Domains, or TLDs. .com is the most famous. .xyz is one too. TLDs
aren’t all the same: So please be mindful of the cost, legal
requirements, and technical limitations that might apply to the
particular TLD that you choose.
The next thing you need to know is that your server is going to have a
name. Its name should be box, plus a period, plus your domain name. In
this example the server’s name will be box.joshmail.xyz. This is also
going to be the address on the web for your mail services.
Let’s get started by buying a domain name. Go to Gandi.net, which is
my favorite domain name registrar. We first will check if the domain
name I want is available. I’m typing in joshmail.xyz, and in fact it
is available for $5 per year. In order to buy this name, I’m going to
have to create an account at Gandi. You’ll have to enter your name and
a password. This password will give access to your domain name, so
choose something long and secure. You’ll also have to choose a
security question, and again choose something you can give a long and
complicated answer to. Your favorite food is a good question to choose
here. Down at the bottom you’ll have to enter an existing email
address you have. That might be your gmail address. Make sure that
address remains secure as well because anyone with access to your
email will get access to your Gandi account. Then turn off the
newsletter, turn on the anti-spam system and private domain
registration, and turn off reselling of your data. Agree to the
contract and click submit. There are some technical details that it
would like to review with you first, including the contacts for the
domain name and its DNS settings. There is nothing for you to do here
--- we’ll change the DNS settings later. At the bottom of the page
agree to the contract. If there is a special contract for the TLD you
chose, do review it and make sure your use intended use of your domain
name complies with the rules for that TLD. Gandi will show you at the
top of the page that it’s working on your order. Then go through
payment. I already have a Gandi account so I’m going to skip ahead
here.
Once you get inside your account you might see that your order is
still in progress, but once the order is ready and this list is empty
you can head over to the Services tab and your domain name will be
there. Click the domain name to go to its control panel and look it
over to make sure the information you’ve entered so far is correct.
The next step is to get a server. Head over to DigitalOcean.com, which
is my favorite place to get a new server. You’re going to have to
create an account here also. Again, use an existing email address that
you have, like at gmail. I already have an account at DigitalOcean,
but you’ll need to confirm your email address and enter your billing
information before you can go forward. Once you’ve got that done, you
can create a droplet, which is what DigitalOcean calls a server.
You must name your droplet the name we discussed earlier, in my case
box.joshmail.xyz. You also must choose the $10 size or bigger; the $5
size just isn’t powerful enough for mail. And choose the region that’s
closest to you so your server is more responsive. If your region
supports it, turn on IPv6 and enable backups. DigitalOcean will create
backups of your server automatically in case you need them. You must
choose Ubuntu 14.04 x64. That’s the only platform that Mail-in-a-Box
supports.
And then you need to add an SSH key. This is like your front door key
and it’s what gives you administrative access to your new server. In
order to create a key, you’ll need to get to a terminal. This is how
you get to a terminal in Ubuntu Linux. It’s similar on a Mac, totally
different in Windows. Open up a terminal and then you’ll just have to
follow along with these commands. The command will create a key, which
will be stored in two files on disk with lots of random characters.
Type in “ssh dash keygen dash t RSA dash b 4096 dash capital C” and
then some handle for yourself: your twitter account, your firstname,
anything but without any space in it. Hit enter a few times to accept
the defaults for the questions --- although you may enter a passphrase
if you want. The first file this command creates is called the private
key, and it’s stored on your hard drive in the location I’m
highlighting on screen. The private key is private. Do not share it,
do not send it over email, do not copy it to another computer. Never
give it away. The second file is the public key. It goes hand-in-hand
with the private key, but you do give it to other people so they can
identify you. I’m highlighting the location of the public key file on
your hard drive: You should copy it to the clipboard. Then type “cat
space” and then paste the location of the public key file, and press
enter. The terminal will show what’s inside the file. This random text
identifies your private key but doesn’t actually have your private key
in it. Copy the public key to your clipboard, and then switch back to
DigitalOcean. Paste the public key into the box there, label it so
you remember what computer the key is stored on, and then click Add
SSH Key. Then click Create Droplet.
DigitalOcean is now going to spin up a new virtual server for you in
its cloud. The server will be turned on all the time, waiting to send
and receive mail for you. This step takes about a minute and I’m fast-
forwarding ahead in the video. Once it’s finished you’ll be taken to
the control panel for your server.
Copy the IP address of your server to the clipboard. It’s at the
beginning of the line here. Head back over to Gandi and scroll down on
your domain name control panel. Click on Glue Record Management.
Scroll down, and for Name type in ns1 dot box. That stands for name
server one. This is a subdomain of your domain name. Paste in the IP
address. Operations on Gandi take a few moments to go through, and
while that’s happening we’ll add a second glue record. This time enter
ns2 dot box and paste the same IP address again. If you ever add other
domain names to your server, you do not repeat this part.
Once the glue records are in, head back to the main page. Your server
can host mail for more than one domain name, and if you register more
domain names for use with Mail-in-a-Box you will have to do this next
part for ea ch domain name. Go to Modify Servers, and we’re going to
enter ns1.box.joshmail.xyz and ns2.box.joshmail.xyz, replacing
joshmail.xyz with your domain name of course. If you’re repeating this
step later on a second domain name, you still use ns1 dot your
server’s name – not ns1 dot box dot your second domain name.
Now go back to the terminal and we’ll log in to the server using SSH
by typing in: “ssh root at” and the IP address of your server. If
you’re concerned about security you may want to confirm the host key
fingerprint. I’m showing in the little popup what to check it against
at DigitalOcean. Type in “yes” and press enter. And now we need to
grab the Mail-in-a-Box installation command, so head over to
mailinabox.email. Look for the command that starts with “curl” and
ends with “bash.” Copy it to the clipboard and paste it into the
terminal, and press enter.
This starts the real Mail-in-a-Box setup. Mail-in-a-Box is going to
download software and configure your server to run as a mail server.
It will ask you a few questions. You can choose another email address
at this point but don’t change the domain name. It will confirm the
server’s name -- just press enter. Now use the down key on your
keyboard to choose your country and hit enter.
This next part takes about 10 minutes, and I’ll speed this up in the
video so we can get through it quickly. Mail-in-a-Box itself is just
system configuration, pulling in other people’s software and
configuring it.
At the end of the installation it will ask you for a mail password,
for checking your mail in webmail and on your devices, and for access
to the server’s own Mail-in-a-Box control panel which you’ll see in
just a moment. Choose a secure password and enter it twice.
It now gives you instructions for the next step. Copy the new control
panel address and open it up in your web browser. Because we don’t
have an SSL certificate yet, the connection can’t be verified as
secure, although it probably is. If you are concerned about security,
do this part in Firefox and compare the SHA1 fingerprint of the
certificate with the fingerprint printed in the terminal at the very
end of the Mail-in-a-Box installation. Then confirm the exception and
log into your Mail-in-a-Box. Use your new email address and the
password you entered just a moment ago.
It will start you on the system status checks, which check that the
box has been configured correctly so far. And at this point you should
see exactly what I have here. We’ll come back to one of the errors at
the top later. But the green lines and checkmarks indicate that the
box is mostly good. If your page doesn’t look like this, wait 20
minutes and then reload the page. DNS changes can take some time to
take effect.
There is an optional step that we’re going to do now is DNSSEC setup,
which adds enhanced security for DNS. Although it is optional, it is
easy so I recommend it. Expand the DNSSEC information and copy the
DNSSEC public key to the clipboard. Open up the Gandi control panel
again and scroll down to Manage DNSSEC. Change the flags and algorithm
to match what the status checks tell you to use, not necessarily what
is shown here, and paste in the DNSSEC public key, and click Add. It
will take a moment to go through. After a few minutes, reload the
status checks page and ensure that the DNSSEC warning is gone and
instead appears green with a checkmark. This, and anything related to
DNS, could take up to 20 minutes to update.
The next issue it tells us to resolve is a missing SSL certificate.
Head over to the SSL Certificates section of the control panel, click
Install Certificate across from your server’s name, and copy the
Certificate Signing Request, or CSR, to the clipboard. Then go back
to Gandi and click the link to buy a SSL certificate. You need what
they call a Standard SSL certificate, which normally costs $16 a year,
but Gandi gives you one year free with your new domain name, so right
now it’s free. Paste the CSR into the form here. Check that the domain
listed below it is your server’s name. Then choose engine-x, and click
Submit.
There are different ways you can prove to Gandi that you own this
domain name, but the only one that will work for you right now is
Validation by DNS. Select that.
While I’m finishing this on screen, let me tell you want this is. An
SSL certificate is a file installed on your server to enable encrypted
and authenticated communications between your devices and your server.
This is the S in HTTPS, but it is also used in other protocols behind
the scenes. The way this works is that Gandi is going to check that
you are in control of the domain name. They’ll then give you a
certificate file for your server. When your devices connect to your
server, they know to trust Gandi’s certificate.
Your order may be in progress for a moments initially. Reload the page
to see if the pencil icon becomes available. If it does, click it to
see the status of the order and instructions for Validation by DNS.
Copy the beginning of the DNS record it gives you through where it
says box, and then head back to the Mail-in-a-Box control panel.
Switch to the Custom DNS section and paste what’s on your clipboard
into the subdomain box. Change the record type to CNAME. Then go back
to Gandi, copy the last part of the record, including the period at
the end, and paste it into value field in the Mail-in-a-Box control
panel. Click Set Record, and confirm that below it the record was
added.
Now we have to wait for Gandi to check that we’ve added the DNS
record. This part may take half an hour. You’ll get an email from
Gandi when the SSL certificate is ready. When it does, reload this
page. The last step here will still say pending, but ignore that and
head back to this page which lists all of your SSL certificates.
You’ll have one.
Click the magnifying glass next to your certificate. It will show you
your certificate, which is good for one year. Don’t share the
certificate with anyone. Copy the certificate to your clipboard, and
then head back to the Mail-in-a-Box control panel again and go back to
the SSL certificate installation for your server’s name. Paste the
certificate into the first field. This isn’t actually enough. Gandi
issues you a certificate but also gives you an intermediate
certificate chain, which is used by all of their customers. Copy the
intermediate certificate chain and paste it into the second field in
the control panel. Submit that.
Now if we visit the website at box.joshmail.xyz we’ll see it has a
secure connection using the SSL certificate.
Because we just installed a new certificate on the page we were
viewing, Firefox has gotten all confused. But we can actually just
open up the control panel at a better address using the server’s name,
rather than it’s IP address: https colon slash slash box.joshmail.xyz
slash admin. Log in again.
It will run the status checks again, and now the SSL certificate line
will be in green, it says it is signed and valid, and it will let you
know how long until the certificate expires. Everything looks.
The last issue we’ll address is that the status checks have been
telling us a reboot of the server is necessary. Go back into the
terminal, which should still be logged into your server, type reboot,
and press enter. Your server will log you out and then reboot.
DigitalOcean servers reboot super fast, so once we get back to the
terminal I’ll show you how to log back in – this time using the
server’s name, rather than it’s IP address. This is the same address
again, box.joshmail.xyz, which is much easier to remember than the IP
address. This is the same confirmation as earlier. In the future, if
you need to reboot, you can do that from here. If you need to re-run
the setup because something went wrong, just type in “mailinabox” and
press enter. Type logout and press enter when you are done.
You server is now working. Refresh the status checks to see that the
errors are all gone – unless you have this one, which is actually OK
for now.
Check out the rest of the control panel for instructions on setting up
your devices and accessing webmail. You use your new email address &
password. You can also add other users to your server so they can have
their own mailboxes too. Aliases are like forwarders, and actually you
already have some. You can also store your contacts and your calendar
on your server and have it synchronized with your devices – those
instructions are here too. We use the ownCloud component for that.
Again you use your new email address and password to log in to that.
There’s also a simple website hosting, but you may need to buy another
SSL certificate for other domain names you put website at in order to
remove the security warning.
And that’s it. Check the setup guide on the Mail-in-a-Box website for
anything I may have missed in this video. There’s also a link there to
the discussion forums if you have any questions. Follow Mail-in-a-Box
on twitter for important announcements. And for more security, turn on
two-factor authentication at Gandi, DigitalOcean, and at your old
email provider if possible, since you used that address for your Gandi
and DigitalOcean accounts. Now get mailing!
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment