# Add a custom domain

Every [solution ](/getting-started/key-concepts.md#solution)in Appfarm comes with a unique name and a unique `appfarm.app` URL. For example, your solution may be named ThirtyFifty Inc, having `thirtyfifty.appfarm.app` as URL to the production environment. 

Appfarm also supports custom URLs for the production environment. For example, you may want to use `portal.thirtyfifty.com` instead.

For the above example of ThirtyFifty Inc, here are the prerequisites and steps to be followed. 

#### **Prerequisites**

* You need access to the operator of the `thirtyfifty.com` domain. This is normally some department or employee of ThirtyFifty Inc (but this is sometimes outsourced as well)
* You need either a dedicated subdomain (such as `portal.thirtyfifty.com`) or the root domain (such as `thirtyfifty.com`) to be pointed towards the `appfarm.app` domain. You *cannot* point a URL such as `thirtyfifty.com/portal`to the `appfarm.app` domain, when `thirtyfifty.com` is already being used for the main website. In this case, you will need to create a subdomain `portal.thirtyfifty.com`.
* You may only have 1 custom domain, and that domain must point to the root appfarm domain. Example: You *cannot* point `portal.thirtyfifty.com` to a subdirectory such as  `thirtyfifty.appfarm.app/myapp`.  See explaination in [Comments](/how-to/security-testing-and-deployment/add-a-custom-domain.md#comments).

#### **Steps**

1. **By the Customer** (technical operator of thirtyfifty.com): Create a subdomain such as portal.thirtyfifty.com (the name "portal" may be something else also). CNAME records of portal.thirtyfifty.com must be mapped to thirtyfifty.appfarm.app.
2. **By Appfarm:** Let Appfarm know when step 1 is done, and we will complete the setup on our side. 

#### Comments

* Note that both the appfarm.app domain and the new custom domain will work after a new custom domain has been configured. 
* The reason why you cannon map `portal.thirtyfifty.com` directly to the App (i.e. subdirectory) `thirtyfifty.appfarm.app/myapp`, is that the CNAME mapping translates to an IP address (that targets the root `thirtyfifty.appfarm.app`). 
* Example: You want custom domain `mypage.thirtyfifty.com` to point directly to the app "My Page" and another domain `admin.thirtyfifty.com` to point to the app "Admin". Due to the reason explained in the previous point, that is not possible. The solution is to have a single custom domain, for example `app.thirtyfifty.com` (pointing towards `thirtyfifty.appfarm.app`). That would result in the following directlinks to the apps: `app.thirtyfifty.com/mypage` and `app.thirtyfifty.com/admin`.
* If you distribute the URL `portal.thirtyfifty.com` to your users - the users will remain in this domain while using the App. Also, if your App makes use of `App Variables.Hostname`, the value of this variable will be the current hostname (`portal.thirtyfifty.com`). The new domain is the default domain for Services (which may also use `Service Variables.Hostname` for constructing URLs if used for sending emails).

{% hint style="warning" %}
In the case where your organization has CAA records (Certification Authority Authorization) for the top domain (e.g. `thirtyfifty.com`), **Let's Encrypt** (letsencrypt.org) must be specified as a supported Certificate Authority. You must add a CAA record that should look something like this: **0 issue “letsencrypt.org”.**\
\
Without this, Appfarm cannot generate valid certificates for subdomains (e.g. `portal.thirtyfifty.com`), since Appfarm is using Let's Encrypt as CA.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.appfarm.io/how-to/security-testing-and-deployment/add-a-custom-domain.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.