Domains #

You can see the Domains an app can be reached on with domain.

setops -p <PROJECT> -s <STAGE> --app <APPNAME> domain

Private Domain #

An App always has a private domain at app.stage.project.<YOURDOMAIN>.internal (e.g. web.staging.parkscheibe.setopsapps.internal), only resolvable by apps within the same SetOps stage. The purpose of this domain is that Apps can reach each other without the need to be exposed to the internet.

Public Default Domain #

An App is also available via a public default domain at app.stage.project.<YOURDOMAIN> (e.g. web.staging.parkscheibe.setopsapps.net), when the App is set to public.

Public Custom Domains #

In addition to the default domain for your app, you can configure any number of public custom_domains where the App should be reachable at. TLS certificates will be automatically maintained for your custom domains. Once you have set up the DNS records for the custom domain and it is validated, there is no maintenance needed from your side to monitor and renew TLS certificates.

...
apps:
  <APPNAME>:
    ...
    custom_domains:
      <DOMAIN>:
         primary: false
         validated: false
         redirect_to_primary: true
         static_ips: false
    ...

When adding a domain, you must first apply your changes with validated set to false. See validated.

primary #

An app can have any number of custom domains but only one can have primary set to true. The primary domain is where your app will be served. Any other domain (custom domains or the default domain) will redirect to your primary domain by default.

validated #

Custom domains have to be validated to be used. With SetOps, all HTTP traffic is TLS-encrypted by default. The validation checks if the Validation Record(s) are present on the given custom domain for being able to issue TLS certificates for that domain.

After you added a domain with validated set to false and applied the change, you can view the necessary DNS configuration by running domain for the corresponding app.

setops -p <PROJECT> -s <STAGE> --app <APPNAME> domain

3 Domain(s) configured.


Domain setops.co
   Primary:     true
   Validated:   false

   ⏳ This domain has not yet been validated.
   After setting the validation records below, wait until they are visible on the DNS server.
   Then validate the domains via app:domain:validate command.
   The app will not be served at this domain until it is validated successfully.

   Custom Domain Record(s):
      Name:                 setops.co
      Type:                 CNAME
      Value:                web.production.project1.<YOURDOMAIN>
      Alternative Type:     A
      Alternative Values:   1.2.3.4,4.3.2.1

   Validation Record(s):
      Name:    _bf54355ea06621c5c64f2c39af899101.setops.co.
      Type:    CNAME
      Value:   _5a892a6631c5d51bc87519faa60b8624.duyqrilejt.acm-validations.aws.

Domain web.production.project1.<YOURDOMAIN>
   Primary:     false
   Validated:   true

   The default domain for this app.
   This domain cannot be deleted.


Domain web.production.project1.<YOURDOMAIN>.internal
   Primary:     false
   Validated:   true

   The private domain for this app.
   This domain is only available from Apps and One-Off Tasks of this Stage.

The custom domain Records and Validation Records instruct you how to configure the DNS for the custom domain.

For a custom domain record, there is a default record type and an optional alternative record type:

• The default record type should be used whenever possible. It is a CNAME (alias) record that points to a SetOps domain and provides the best interoperability and reliability.

• The alternative record type may be used when the default record is not applicable. This may happen with a domain APEX (e.g. setops.co), but should not happen with subdomains (e.g. api.setops.co). It is property of the DNS that CNAME records can not be used for a domain APEX. While some popular DNS providers have built features to work around this issue, some do not and this is when the alternative record must be used. CNAME records for APEX domains are sometimes called ANAME or ALIAS records. Refer to your DNS provider’s documentation to learn more if and how they support this.

After you have added the DNS records, validate your custom domain by setting validated to true. Wait an appropriate time after setting the DNS records for the DNS servers to refresh.

...
apps:
  <APPNAME>:
    ...
    custom_domains:
      <DOMAIN>:
         primary: false
         validated: true # <--
         redirect_to_primary: true
         static_ips: false
    ...

Please note that it may take several minutes to hours until changes you made to your DNS records become visible for SetOps. In case the validation fails although you made the required changes try again after some time.

You can verify that the DNS records are set correctly with the dig utility on your local computer:

dig _bf54355ea06621c5c64f2c39af899101.setops.co. @1.1.1.1 +short

The command output should show the record you set earlier:

_5a892a6631c5d51bc87519faa60b8624.duyqrilejt.acm-validations.aws.

If dig does not print the expected value, double check your DNS settings and try again later, as DNS changes may take some time to propagate through the system.

redirect_to_primary (optional) #

Domains which are not set to be primary can be configured to also forward traffic to the app in addition to the primary domain. To do so redirect_to_primary must be set to false. It defaults to true.

static_ips (optional) #

Sometimes clients of your application need static, non-changing IP addresses for the app domain, e.g. when they want to allow outgoing traffic to specific IP addresses or when they cannot set CNAME records on APEX domains. In that case and only then set static_ips to true which provides static IP addresses after applying the definition.

💰 Using static IP addresses increases costs.

Public Custom Wildcard Domains #

In addition to the public custom domains described in the previous section, you can also add public wildcard domains. If you configure a wildcard domain, e.g. *.setops.co, your app will be reachable on all subdomains of this domain, e.g. api.setops.co, docs.setops.co, www.setops.co.

Custom wildcard domains cannot have set the field primary to true since other domains cannot redirect to a wildcard domain.

Just add a custom domain with the wildcard notation (*.<your domain>) like you would do with a single domain and set redirect_to_primary to false in case you want your app to be reachable via all subdomains:

...
apps:
  <APPNAME>:
    ...
    custom_domains:
      "*.<your domain>":
         primary: false
         validated: true
         redirect_to_primary: false
    ...

Going further #

Schedule app commands.