Setting Up Domains, DNS, and SSL Certificates

This guide provides an overview of how to set up a custom domain on a production Instance using either platformOS's DNS web service or an external DNS web service as well as create and provision an AWS SSL certificate for your Instance.

Requirements

To be able to set up a production domain on the Partner Portal, you have to have access to the Partner Portal, have a production Instance, and you should be familiar with the recommended development workflow.

• Register on the Partner Portal
• Create an Instance
• Development Workflow

There are a couple things to consider before you add a custom domain to your platformOS production Instance:

1. A domain can only be added on a production data center. This means that you cannot set up an additional domain on a staging data center Instance.
2. PlatformOS Instances require the ability to apply a Fully Qualified Domain Name (FQDN) to a DNS record. If your DNS management service does not allow for that, you will need to change providers or opt to use the free fully integrated hosted zone that is provided to you as a benefit of hosting with platformOS. When setting up your custom domain, this is the first decision you must make.
3. We automatically provision and deploy AWS SSL certificates when you add a domain to a platformOS Instance. To apply custom SSL certificates, please contact support@platformOS.com and we will assist further.

Let's begin.

Will you be using the platformOS DNS service? Click "Yes" or "No" below:

Yes — Show me how to set up a custom domain using the platformOS DNS service
No — Show me how to set up a custom domain using an external DNS service

I. Custom Domain using platformOS DNS service

If you will use the platformOS DNS service, then there are 4 basic options when adding a domain to a platformOS Instance:

A. Resolving to www of root domain (example: https://www.example.com)
B. Resolving to root domain (example: https://example.com)
C. Resolving to www of subdomain (example: https://www.123.example.com)
D. Resolving to subdomain (example: https://123.example.com)

You'll find instructions below for each or you can click the letter (A,B,C,D) next to the option that is best for you and it will take you to the correct walkthrough.

A. platformOS DNS and resolving to www of root domain (example: https://www.example.com)

1. Sign into your domain registrar and export your zone file, or save your current DNS records (if any) off to the side so you can add them to the platformOS hosted zone in a later step.
2. Go to the Instance detail page in the platformOS Partner Portal: https://partners.platformos.com/
3. Click “Domains”.
4. Click “Add new domain to your Instance”.
5. Click “DNS Zone”.
6. Add your root domain name (do not add www), check the box if this will be your default domain, and finally click “Create DNS Zone”.
7. From the Domains page, you'll want to refresh the page every few minutes until the status of the new domain changes to "reparking_domain". Once it does, click “view”.
8. Now, add all your DNS records (if any) to the newly created DNS Zone by clicking "add additional record" to add each new record. This is all done 'offline' so this won't impact your current live settings if your domain is currently in use. When done, click “Commit DNS Changes”.

   
   When you are ready to "Go Live", please continue.

9. Update the nameservers in your domain registrar and click “Save”.
10. Once the nameservers are recognized in your domain registrar, click "I have changed Name Servers" on the DNS Zone page in your partner portal.
11. Depending on how quickly the nameserver changes propagate, (from a few minutes, to a few hours), you may have to click 'I have changed Name Servers" a few times and refresh the page a few times. Do not be concerned if some of the records you created in the hosted zone appear and dissappear in the first few minutes after you update the nameservers. Once the Hosted Zone recognizes the change in nameservers, the stats for all your records should be "OK" and you should be all set.
12. Congratulations! An SSL certificate has been created and applied to your Instance and your domain is now LIVE!

B. platformOS DNS and resolving to root domain (example: https://example.com)

1. Sign into your domain registrar and export your zone file, or save your current DNS records (if any) off to the side so you can add them to the platformOS hosted zone in a later step.
2. Go to the Instance detail page in the platformOS Partner Portal: https://partners.platformos.com/
3. Click “Domains”.
4. Click “Add new domain to your Instance”.
5. Click “DNS Zone”.
6. Add your root domain name (do not add www), check the box if this will be your default domain, and finally click “Create DNS Zone”.
7. From the Domains page, you'll want to refresh the page every few minutes until the status of the new domain changes to "reparking_domain". Once it does, click “view”.
8. Now, add all your DNS records (if any) to the newly created DNS Zone by clicking "add additional record" to add each new record. This is all done 'offline' so this won't impact your current live settings if your domain is currently in use. When done. Click “Commit DNS Changes”.

   
   When you are ready to "Go Live", please continue.

9. Update the nameservers in your domain registrar and click “Save”.
10. Once the nameservers are recognized in your domain registrar, click "I have changed Name Servers" on the DNS Zone page in your partner portal.
11. Depending on how quickly the nameserver changes propagate (from a few minutes to a few hours), you may have to click 'I have changed Name Servers" a few times and refresh the page a few times. Do not be concerned if some of the records you created in the hosted zone appear and dissappear in the first few minutes after you update the nameservers. Once the Hosted Zone recognizes the change in nameservers, the stats for all your records should be "OK" and you should be all set.
12. Currently this process will create a www subdomain and a redirect from the root domain to the subdomain. We need to remove that. From the Instance detail page, click on "Domains".
13. We will improve this shortly, but for now, in the URL that appears, remove the /pp_dns. Example: https://partners.platformos.com/instances/5253/pp_dns/domains would be changed to https://partners.platformos.com/instances/5253/domains - From this page, we will remove the redirect from root to www, and add a redirect from www to root. Click 'Edit' on the root domain.
14. Make sure that "Use as default" is checked and that "redirect" is unchecked. Then click "Update Domain".
15. Next, click on "edit" for the www subdomain.
16. Finally, make sure 'Use as default' is unchecked and check "redirect". Add the direct URL to the root domain and then choose your redirect code. Once completed, click "Update Domain".
17. Congratulations! An SSL certificate has been created and applied to your Instance and your domain is now LIVE!

C. platformOS DNS and resolving to www of subdomain (example: https://www.marketplace.example.com)

1. Go to the Instance detail page in the platformOS Partner Portal: https://partners.platformos.com/
2. Click “Domains”.
3. Click “Add new domain to your Instance”.
4. Click “DNS Zone”.
5. Add your subdomain name (do not add www), check the box if this will be your default domain, and finally click “Create DNS Zone”.
6. From the Domains page, you'll want to refresh the page every few minutes until the status of the new domain changes to "reparking_domain". Once it does, click “view”.

   
   When you are ready to "Go Live", please continue.

7. In your root domains DNS records, add the nameserver records for the subdomain with the values provided in the Parter Portal.
8. Once the nameservers are recognized, you can click "I have changed Name Servers" on the DNS Zone page.
9. Depending on how quickly the nameserver changes propagate, (from a few minutes to a few hours), you may have to click 'I have changed Name Servers" a few times and refresh the page a few times. Do not be concerned if some of the records you created in the hosted zone appear and dissappear in the first few minutes after you update the nameservers. Once the Hosted Zone recognizes the change in nameservers, the stats for all your records should be "OK" and you should be all set.
10. Congratulations! An SSL certificate has been created and applied to your Instance and your domain is now LIVE!

D. platformOS DNS and resolving to subdomain (example: https://marketplace.example.com)

1. Go to the Instance detail page in the platformOS Partner Portal: https://partners.platformos.com/
2. Click “Domains”.
3. Click “Add new domain to your Instance”.
4. Click “DNS Zone”.
5. Add your subdomain name (do not add www), check the box if this will be your default domain, and finally click “Create DNS Zone”.
6. From the Domains page, you'll want to refresh the page every few minutes until the status of the new domain changes to "reparking_domain". Once it does, click “view”.

   
   When you are ready to "Go Live", please continue.

7. In your root domains DNS records, add a nameserver record for the subdomain with the values provided in the parnter portal. (If the root domain is hosted on platformOS, then you will click 'update' and then click "Commit DNS Changes", it may be different on other DNS services.)
8. Once the nameservers are recognized, you can click "I have changed Name Servers" on the DNS Zone page.
9. Depending on how quickly the nameserver changes propagate (from a few minutes to a few hours), you may have to click 'I have changed Name Servers" a few times and refresh the page a few times. Do not be concerned if some of the records you created in the hosted zone appear and dissappear in the first few minutes after you update the nameservers. Once the Hosted Zone recognizes the change in nameservers, the stats for all your records should be "OK" and you should be all set.
10. Currently this process will create a www subdomain and a redirect from the root domain to the subdomain. We need to remove that. From the Instance detail page, click on "Domains".
11. We will improve this shortly, but for now, in the URL that appears, remove the /pp_dns. Example, https://partners.platformos.com/instances/5253/pp_dns/domains we would change to https://partners.platformos.com/instances/5253/domains - From this page, we will remove the redirect from root to www, and add a redirect from www to root. Click 'Edit' on the root domain.
12. Make sure that "Use as default" is checked and that "redirect" is unchecked. Then click "Update Domain".
13. Next, click on "edit" for the www subdomain.
14. Finally, make sure 'Use as default' is unchecked and check "redirect". Add the direct URL to the root domain and then choose your redirect code. Once completed, click "Update Domain".
15. Congratulations! An SSL certificate has been created and applied to your instance and your domain is now LIVE!

II. Custom Domain using an external DNS service

If you will be using an external DNS service, there are 4 basic options when adding a custom domain to platformOS.

They are:

E. Resolving to www of root domain (example: https://www.example.com)
F. Resolving to root domain (example: https://example.com)
G. Resolving to www of subdomain (example: https://www.123.example.com)
H. Resolving to subdomain (example: https://123.example.com)

You'll find instructions below for each or you can click the letter (E,F,G,H) next to the option that is best for you and it will take you to the correct walkthrough.

E. External DNS and resolving to www of root domain and using EXTERNAL DNS service (example: https://www.example.com)

1. In our example, we are assuming that your domain has already been set up before with your DNS provider and all records are in place from previous usage.
2. Go to the Instance detail page in the platformOS Partner Portal: https://partners.platformos.com/
3. Click “Domains”.
4. Click “Add new domain to your Instance”.
5. Click “External DNS management”.
6. Add your root domain name (do not add www), will this be your default domain, click "Create External DNS management"
7. Refresh your page a few times until the status on the Domains page changes to 'ownership_verification_pending'. Once it does, click 'view'.
8. We need to validate ownership of the domain so, in your DNS provider, please add the required CNAME record.
9. Once you have added the CNAME, you can click "Ok. Done. I added requested records".
10. Refresh the page a few times (this may take longer) to allow for our system to verify the CNAME. Once it's done, you'll be provided with a couple options for FQDN's depending if your DNS provider is AWS or another provider. You'll also be asked to add the www CNAME record if you have not done so already for your domain. The reason for this is we automatically set up the www subdomain and redirect the root domain to it.

    
    When you are ready to "Go Live", please continue.

11. Add the provided FQDN to your DNS service as an ANAME record. It may take some time for the DNS records to update depending on your DNS service, but normally it's only a few mintues to a few hours.
12. Congratulations! An SSL certificate has been created and applied to your instance and your domain is now LIVE!

F. External DNS and resolving to the root domain and using EXTERNAL DNS service (example: https://example.com)

1. In our example, we are assuming that your domain has already been set up before with your DNS provider and all records are in place from previous usage.
2. Go to the Instance detail page in the platformOS Partner Portal: https://partners.platformos.com/
3. Click “Domains”.
4. Click “Add new domain to your Instance”.
5. Click “External DNS management”.
6. Add your root domain name (do not add www), will this be your default domain, click "Create External DNS management"
7. Refresh your page a few times until the status on the Domains page changes to 'ownership_verification_pending'. Once it does, click 'view'.
8. We need to validate ownership of the domain so, in your DNS provider, please add the required CNAME record.
9. Once you have added the CNAME, you can click "Ok. Done. I added requested records".
10. Refresh the page a few times (this may take longer) to allow for our system to verify the CNAME. Once it's done, you'll be provided with a couple options for FQDN's depending if your DNS provider is AWS or another provider. You'll also be asked to add the www CNAME record if you have not done so already for your domain. The reason for this is we automatically set up the www subdomain and redirect the root domain to it.

    
    When you are ready to "Go Live", please continue.

11. Add the provided FQDN to DNSMadeEasy as an ANAME record.
12. Currently this process will create a www subdomain and a redirect from the root domain to the subdomain. We need to remove that. From the instance detail page, click on "Domains".
13. We will improve this shortly, but for now, in the URL that appears, remove the /pp_dns. Example, https://partners.platformos.com/instances/5253/pp_dns/domains we would change to https://partners.platformos.com/instances/5253/domains - From this page, we will remove the redirect from root to www, and add a redirect from www to root. Click 'Edit' on the root domain.
14. Make sure that "Use as default" is checked and that "redirect" is unchecked. Then click "Update Domain".
15. Next, click on "edit" for the www subdomain.
16. Finally, make sure 'Use as default' is unchecked and check "redirect". Add the direct URL to the root domain and then choose your redirect code. Once completed, click "Update Domain".
17. Congratulations! An SSL certificate has been created and applied to your instance and your domain is now LIVE!

G. External DNS and resolving to the www of a subdomain and using EXTERNAL DNS service (example: https://www.123.example.com)

1. In our example, we are assuming that your domain has already been set up before with your DNS provider and all records are in place from previous usage.
2. Go to the Instance detail page in the platformOS Partner Portal: https://partners.platformos.com
3. Click “Domains”.
4. Click “Add new domain to your Instance”.
5. Click “External DNS management”.
6. Add your subdomain name (do not add www), will this be your default domain, click "Create External DNS management"
7. Refresh your page a few times until the status on the Domains page changes to 'ownership_verification_pending'. Once it does, click 'view'.
8. We need to validate ownership of the subdomain so, in your DNS provider, please add the required CNAME record.
9. Once you have added the CNAME, you can click "Ok. Done. I added requested records".
10. Refresh the page a few times (this may take longer) to allow for our system to verify the CNAME. Once it's done, you'll be provided with a couple options for FQDN's depending if your DNS provider is AWS or another provider. You'll also be asked to add the www CNAME record if you have not done so already for your domain. The reason for this is we automatically set up the www subdomain and redirect the root domain to it.

    
    When you are ready to "Go Live", please continue.

11. Add the provided FQDN to your DNS service as an ANAME record for the subdomain. It may take some time for the DNS records to update depending on your DNS service, but normally it's only a few mintues to a few hours.
12. Congratulations! An SSL certificate has been created and applied to your instance and your domain is now LIVE!

H. External DNS and resolving to a subdomain and using EXTERNAL DNS service (example: https://123.example.com)

1. In our example, we are assuming that your domain has already been set up before with your DNS provider and all records are in place from previous usage.
2. Go to the Instance detail page in the platformOS Partner Portal: https://partners.platformos.com
3. Click “Domains”.
4. Click “Add new domain to your Instance”.
5. Click “External DNS management”.
6. Add your subdomain name (do not add www), will this be your default domain, click "Create External DNS management"
7. Refresh your page a few times until the status on the Domains page changes to 'ownership_verification_pending'. Once it does, click 'view'.
8. We need to validate ownership of the subdomain so, in your DNS provider, please add the required CNAME record.
9. Once you have added the CNAME,instance you can click "Ok. Done. I added requested records".
10. Refresh the page a few times (this may take longer) to allow for our system to verify the CNAME. Once it's done, you'll be provided with a couple options for FQDN's depending if your DNS provider is AWS or another provider. You'll also be asked to add the www CNAME record if you have not done so already for your domain. The reason for this is we automatically set up the www subdomain and redirect the root domain to it.

    
    When you are ready to "Go Live", please continue.

11. Add the provided FQDN to DNSMadeEasy as an ANAME record.
12. Now we need to remove the WWW redirect. From the instance detail page, click on "Domains".
13. We will improve this shortly, but for now, in the URL that appears, remove the /pp_dns. Example, https://partners.platformos.com/instances/5253/pp_dns/domains we would change to https://partners.platformos.com/instances/5253/domains - From this page, we will remove the redirect from root to www, and add a redirect from www to root. Click 'Edit' on the root domain.
14. Make sure that "Use as default" is checked and that "redirect" is unchecked. Then click "Update Domain".
15. Next, click on "edit" for the www subdomain.
16. Finally, make sure 'Use as default' is unchecked and check "redirect". Add the direct URL to the root domain and then choose your redirect code. Once completed, click "Update Domain".
17. Congratulations! An SSL certificate has been created and applied to your instance and your domain is now LIVE!