Approximated Custom Domains and SSL for SAAS Documentation

Virtual Hosts API link

The virtual hosts API is how your application will interface directly with Approximated. You can use it to automate custom domains as needed. There are four endpoints to create, read, update, and delete a virtual host.

Note:
Make sure that you include headers for Content-Type and Accept set to 'application/json' for all requests to the API.

Create Virtual Host link

Creating a virtual host is done with a JSON POST request to the Approximated API. It can be created at any time before or after the custom domain is pointed at the cluster with a DNS record.

{
  "data": {
    "id": 445922,
    "incoming_address": "acustomdomain.com",
    "target_address": "myapp.com",
    "target_ports": "443",
    "user_message": "In order to connect your domain, you'll need to have a DNS A record that points acustomdomain.com at 213.188.210.168. If you already have an A record for that address, please change it to point at 213.188.210.168 and remove any other A records for that exact address. It may take a few minutes for your SSL certificate to take effect once you've pointed your DNS A record."
  }
}
        

Read Virtual Host link

Use a GET request with the incoming_address at the end of the URL to retrieve the details of a single Virtual Host. If that Virtual Host was created with the API Key included in the header, it's details will be returned.

{
  "data": {
    "apx_hit": true, // requests are reaching the cluster
    "created_at": "2023-04-03T17:59:28", // UTC timezone
    "dns_pointed_at": "213.188.210.168", // DNS for the incoming_address
    "has_ssl": true,
    "id": 405455,
    "incoming_address": "acustomdomain.com",
    "is_resolving": true, // is this returning a response
    "last_monitored_humanized": "1 hour ago",
    "last_monitored_unix": 1687194590,
    "ssl_active_from": "2023-06-02T20:19:15", // UTC timezone
    "ssl_active_until": "2023-08-31T20:19:14", // UTC timezone, auto-renews
    "status": "ACTIVE_SSL",
    "status_message": "Active with SSL",
    "target_address": "myapp.com",
    "target_ports": "443"
  }
}
        

Update Virtual Host link

Updating a virtual host is done with a JSON POST request to the Approximated API. It can be updated at any time before or after the custom domain is pointed at the cluster with a DNS record. Any optional fields not submitted will remain the same as they were previously.

{
  "data": {
    "apx_hit": true, // requests are reaching the cluster
    "created_at": "2023-04-03T17:59:28", // UTC timezone
    "dns_pointed_at": "213.188.210.168", // DNS for the incoming_address
    "has_ssl": true,
    "id": 405455,
    "incoming_address": "adifferentcustomdomain.com",
    "is_resolving": true, // is this returning a response
    "last_monitored_humanized": "1 hour ago",
    "last_monitored_unix": 1687194590,
    "ssl_active_from": "2023-06-02T20:19:15", // UTC timezone
    "ssl_active_until": "2023-08-31T20:19:14", // UTC timezone, auto-renews
    "status": "ACTIVE_SSL",
    "status_message": "Active with SSL",
    "target_address": "myapp.com",
    "target_ports": "443"
  }
}
        

Delete Virtual Host link

Use a DELETE request with the incoming_address at the end of the URL to remove a single Virtual Host.

Deleting customdomain.com

Integrating With Your App link

When a request for a custom domain reaches your application, you likely want to return content specific to that custom domain. For example, if your app hosts blogs, the custom domain should return content for that particular blog.

Depending on how your application works, you may need to make some changes to your code base. Below are some of the more common scenarios.

Statically Generated Content link

With statically generated content, you probably have folders and files sitting on a server for each custom domain. For example, a request to mybloghost.com/some-blog will load the content directly from the /some-blog folder on your server.

In this situation, there's probably no code being run before that content is loaded directly from the files. You might have caching, but the end result is the same.

For statically generated sites, the easiest way to integrate custom domains is likely to target that user's folder URL directly. With Approximated, you can accomplish this by adding a path to your virtual host target address field.

For example:

There are some obstacles to this approach, however:

Laravel link

Laravel is one of the best frameworks out there, and can easily use custom domains with Approximated. The best way to learn how to integrate Approximated with your Laravel app is to look at our Laravel custom domains example repo.

That repo is a working example that demonstrates setting a custom domain for a user, routing and middleware for custom domains, and custom domain specific controllers/content.

Ruby on Rails link

Ruby on Rails makes integrating with Approximated easy. The best way to learn how to integrate Approximated with your Rails app is to look at our Ruby on Rails custom domains example repo.

That repo is a working example that demonstrates creating pages that can be tied to a custom domain, the routing required, and a class that interfaces with the Approximated API for you.

Elixir Phoenix link

Apps using Elixir's Phoenix framework can integrate with Approximated easily, including websockets for liveview. We've created an example repo here for you to explore, so that you can see for yourself with a working example.