Extend documentation

[cywtf]

I recently spent more time than needed adding external domains to my MiaB due to misunderstanding on how the External DNS configuration worked. I think this could be avoided if the documentation explains the exact steps to get this done, specifically in the sections Multiple Domain Names and Domain Name Configuration > Advanced: External DNS.

Would you be ok if I send a PR and extend the instructions on how to get this done?

Otherwise I could just write an extended tutorial and post it in a place like medium.com, but I thought the official website its the place to start asking.

[JoshData]

Of course! You might want to sketch out in brief here what you plan to write so I can provide some early feedback.

[cywtf]

Great. So I did a very rough brief that needs much more work but its a start. I would keep everything that's there and only add a few things. I think it just needs some reorganization. The biggest change is that I'd clearly specify two different approaches towards DNS setup, depending on whether you want to use a domain exclusively for MiaB (and in this case, the setup is simpler and Mail-in-a-Box take care of the DNS) or not (and in this case, you need to do the DNS setup yourself).

Looking forward to your feedback!

Summary

• Requirements

  • Finding a cloud service provider
  • Choosing the right domain
  • Dedicated domain vs domain for multiple uses
  • Multiple domains in your Mail-in-a-Box
  • TLD Domain limitations

• Setting Up

  • Naming your Box

  • DNS Configuration

    • Glue Records & Nameservers
    • External DNS Configuration

  • Installing the Box

  • Configuration

    • Add a TLS (SSL) certificate
    • Add more domains
    • Create users
    • Set up your email client
    • Set up contact and calendar synchronization
    • Check backups status

• Frequent Questions

---

Requirements

• A machine with at least 1 GB of RAM and newly installed Ubuntu 14.04 x64 operating system.

• A domain name you own.

That's it. Now, ready to rumble.

Finding a cloud service provider

All info that it's on this section

Choosing the right domain

The first step in setting up a Mail-in-a-Box is to pick your new email address. An email address has two parts. The part after the @-sign is the domain name. Each domain name is owned by someone, and you are going to be the owner of your own.

Josh’s email address is [email protected]. His domain name is occams.info.

Dedicated domain vs domain for multiple uses

If you choose to have a domain dedicated to Mail-in-a-Box, the installation will be easier. You will configure what's called the glue-records and Mail-in-a-Box will take care of the DNS configuration for you. This is the recommended set-up.

If you have an existing domain that you are using for something else, like an existing website, and you would want to use this domain for Mail-in-a-Box as well, you need to configure the DNS yourself. See External DNS Configuration for more info.

Multiple domains in your Mail-in-a-Box

You can use your Mail-in-a-Box with several domains, but you only use one to configure the box. Once the installation is finished and your box is running, you can add the rest of the domains. See Add more domains for further explanation.

TLD Domain limitations

Some domain names have quirks, depending on which “top-level domain” (TLD) it is under. Please consult this list. Add section from here

---

Setting Up

• Naming your Box

• DNS Configuration

  • Glue Records & Nameservers
  • External DNS Configuration

• Installing the box

• Configuration

  • Add a TLS (SSL) certificate
  • Add more domains
  • Create users
  • Set up your email client
  • Set up contact and calendar synchronization
  • Check backups status

Naming your Box

Every machine connected to the Internet has a name and an address.

The address, an IP address, is like a telephone number. It’s made up of numbers and is assigned to you by whoever provides Internet access to you.

The name — called a hostname — is something you decide. It can be a domain name you own or any “subdomain” of a domain you own.

For your Mail-in-a-Box, we recommend naming your box box + . + your domain name.

Josh’s Mail-in-a-Box is named box.occams.info. This is its hostname.

Your Mail-in-a-Box may handle the email for multiple domain names, but the box has a single name.

DNS Configuration

Let Mail-in-a-Box manage DNS for you

If you choose to have a domain dedicated to Mail-in-a-Box, the installation will be easier. You will configure what's called the glue-records and adjust the nameservers and Mail-in-a-Box will take care of the DNS configuration for you.

Glue-records setup

Add this block except Advanced: External DNS.

Nameservers setup

Add this block except Advanced: External DNS.

Now you are ready to continue with Installing the Box.

Manage DNS yourself

If you have an existing domain that you are using for something else, like an existing website, and you would want to use this domain for Mail-in-a-Box as well, you need to configure the DNS yourself, such as in the DNS control panel provided by your domain name registrar or virtual cloud provider, and you do that following the next steps.

External DNS Configuration

First you will need to follow the installation instructions specified in Installing the box, using your [Box Name](#Naming your Box) as a Hostname. Follow the process until the end and let it finish.

Because your DNS are not set up yet, the installer will give you an admin URL consisting in IP address that you can open in your browser and log in your box for the first time. Do that using the credentials you created (email and password) during installation.

As you will do if you want to add more domains, if you access System > External DNS you will see all the records you need to add in your DNS Manager in order to point those DNS to your Mail-in-a-Box.

The MX Record is the only one required here. Ignore the mandatory line for the A Record of your domain.com. The System Status Checks will yell that the The nameservers set on this domain are incorrect and that the This domain should resolve to your box's IP address, but this is something you can ignore as you want to keep these records somewhere else.

You should add the recommended records to your DNS Manager as they guarantee extra validation and security.

Installing the Box

Add all the instructions from Setting Up The Box and The Administrative Interface.

Configuration

• Add a TLS (SSL) certificate
• Add more domains
• Create users
• Set up your email client
• Set up contact and calendar synchronization
• Check backups status

This needs to be added.

---

Frequent Questions

• Can I run my Mail-in-a-Box at home?

• What will it cost?

• How much time does it take?

• Can I host a website in the same domain I use for Mail-in-a-Box?

• Can I modify my box after / use my box for something else too? (Advanced.)

[JoshData]

Hey.

You don't need to use external DNS if you are using your domain for other things because you can use the Custom DNS page on the box's control panel to add whatever records you need. I use my box this way for a high traffic site (which is hosted elsewhere) and have no problems.

So, rather than trying to rewrite the whole setup guide, it will be a lot easier/faster to improve it if we start in a particular section and try to figure out what the minimum change we can make is to make it clearer.

[alento-group]

Hi @JoshData Of late so many issues in the forum have been related to DNS - namely using two (or more) domains, secondary dns, and external DNS. I would like to suggest that we rewrite the installation guide to have a brief overview so that people can determine which way they need to proceed and then to edit the guide to have a different path for the methodology chosen. I understand your position on how it is not necessary to use external DNS and I agree for the most part, but it seems that there are too many people wanting to follow a different path, so let's make it easier for them (and less work in the forums chasing DNS issues!), Thoughts?