📘

Note

This tutorial assumes you already have a web app running on Aptible. If you don't have, you can easily create one for testing like so:

First, create a new app on Aptible ($APP_HANDLE below refers to the handle you pick for your app).

Second, deploy a web server to this app using the aptible deploy command:

Shell

aptible deploy --app "$APP_HANDLE" --docker-image httpd

This tutorial will walk you through the process of setting up a HTTP(S) Endpoint with External Placement, using a Custom Domain and Managed TLS.

Unpacking this sentence a little bit, this means:

• HTTP(S) Endpoint: the Endpoint will accept HTTPS and HTTP traffic. Aptible will handle HTTPS termination for you, so your app simply needs to process HTTP requests.
• External Placement: the Endpoint will be reachable from the public internet.
• Custom Domain: the Endpoint will use your own domain (e.g. www.example.com).
• Managed TLS: Aptible will provision a SSL / TLS certificate on your behalf.

There are plenty of other choices here. To learn more about those, head on over there: Endpoints.

Here is the overall process:

Create the Endpoint

In the Aptible Dashboard, create a new Endpoint.

Use the following options and leave the ones that aren't mentioned as default:

• Type: Custom Domain with Managed HTTPS.
• Endpoint Placement: External.
• Domain Name: the domain name you intend to use. In the example above, that was www.example.com, but yours will be different.

Click save, then wait for the Endpoint to provision. If that fails, jump to Endpoint Provisioning Failed.

📘

Tip

The domain name you choose should not be a domain apex. For example, www.example.com is fine, but just example.com is not.

For more information, see: How do I use my domain apex with Aptible?

Create a CNAME to the Endpoint

Once the Endpoint is provisioned, you'll be presented with an Endpoint Hostname and Managed HTTPS Validation Records.

The two have different, but overlapping use cases.

Endpoint Hostname

The Endpoint Hostname is a domain name that points to your Endpoint.

However, you shouldn't send your traffic directly there. Instead, you should create a CNAME DNS record (using your own DNS provider) from the name you intend to use with your app (www.example.com in the example above) to the Endpoint Hostname.

So, create that CNAME now.

Validation Records

The validation records serve a slightly different purpose: they're used by Managed TLS to provision a certificate for your domain via Let's Encrypt.

When you create those records, Aptible can work for you and provision certificates. If you don't create them, then Let's Encrypt won't let Aptible provision certificates for you.

Now, as it happens, the CNAME you created for the Endpoint Hostname is also a validation record. That makes sense: you're sending your traffic to the Endpoint, that's enough proof for Let's Encrypt that you're indeed using Aptible and that we should be able to create certificates for you.

You'll note that there are two validation records. We recommend you create both, but you're not going to need the second one (the one starting with _acme-challenge) for the purposes of this tutorial.

Validate the Endpoint

Once you've created the CNAME from the domain name you're using to the Endpoint Hostname, click the confirmation button in the Dashboard.

Aptible will provision a certificate for you, then deploy it across your app.

If all goes well, you'll see a success message (if not, see Endpoint Certificate Renewal Failed below).

At this point, you can navigate to your custom domain (over HTTP or HTTPS), and your app will be accessible.

Next Steps

Now that your app is available over HTTPS, it's a good idea to enable an automated HTTPS Redirect.

Going forward, you can also learn more about Endpoints here: Endpoints.

Troubleshooting

Endpoint Provisioning Failed

If Endpoint provisioning fails, you'll see a prompt to restart your app using the aptible restart command. Do so as instructed.

Note that this failure is most likely due to an app health check failure. We have troubleshooting instructions for this over here: My deploy failed with HTTP health checks failed.

If this doesn't help, contact Aptible Support.

Endpoint Certificate Renewal Failed

This failure is probably due to an issue with the CNAME you created.

There are two possible causes here:

• The CNAME change is taking a little to propagate. Here, it's a good idea to wait for a few minutes (or seconds, if you're in a hurry!) then retry via the Dashboard.
• The CNAME is wrong. A good way to check for this is to access your domain name (www.example.com in the examples above, but yours will be different). If you see an Aptible page telling you you're almost done, you probably got it right, and you can retry via the Dashboard. If not, then double-check the CNAME you created, there's probably a problem there;

If this doesn't help, contact Aptible Support.