neeto-custom-domains-nano

The neeto-custom-domains-nano manages custom domains across neeto applications.

Contents

1. Development with Host application
2. Instructions for publishing

Development with Host application

The engine provides the backend setup for neetoCustomDomains.

Installation

1. Add this line to your application's Gemfile:

source "NEETO_GEM_SERVER_URL" do
  # ... existing gems

  gem "neeto-custom-domains-engine"
end

2. And then execute:

bundle install

3. Run migrations

rails neeto_custom_domains_engine:install:migrations
rails db:migrate

Usage

1. Add association

# If custom domain is associated to Organization
class Organization < ApplicationRecord
  include NeetoCustomDomainsEngine::CustomDomainable
end

# If custom domain is associated to other resources (eg: Site)
class Site < ApplicationRecord
  include NeetoCustomDomainsEngine::CustomDomainable
end

The concern adds the custom_domains association, primary_custom_domain and canonical_root_url(fallback). Remove any has_many :custom_domains or primary_custom_domain the model already defines. A model method overrides the concern's, and the concern's version returns only an active domain without a redirection, which canonical URLs and the redirect rely on.

2. Add controller

All common controller logic is extracted to the engine. However, we still need to load some records from the host app controller.

If the custom domain is associated with Organization, add a Api::V1::CustomDomainable concern in the host app and include it in the controller. This keeps the loader reusable across controllers that need it.

# app/controllers/concerns/api/v1/custom_domainable.rb
module Api::V1::CustomDomainable
  extend ActiveSupport::Concern

  private

    def load_custom_domainable!
      @custom_domainable = organization
    end
end

class Api::V1::Admin::CustomDomainsController < NeetoCustomDomainsEngine::DomainsController
  include Api::V1::CustomDomainable
end

If the custom domain is associated with another resource (eg. Site), define load_custom_domainable! directly in the controller instead:

class Api::V1::Admin::CustomDomainsController < NeetoCustomDomainsEngine::DomainsController
  private

    def load_custom_domainable!
      @custom_domainable = organization.sites.find(params[:site_id])
    end
end

3. Add a CustomDomainConcern model concern

The engine's NeetoCustomDomainsEngine::Domain model needs custom_domain_url and organization to be available on the domain record — they are used, for example, when generating links in notification emails and when pushing the domain to NeetoTower.

Define the concern in the host app at the exact path below. The engine auto-includes it via include CustomDomainConcern if defined?(CustomDomainConcern), so no initializer or manual patching is needed — Rails autoloading handles it.

The path returned by custom_domain_url is product-specific. Point it at wherever the custom domain settings page is mounted in your product's admin panel (the example below uses NeetoQuiz's path; replace it for your product).

# app/models/concerns/custom_domain_concern.rb
module CustomDomainConcern
  extend ActiveSupport::Concern

  def custom_domain_url
    root_url = organization.root_url
    # Replace this path with the route to the custom domain settings page
    # in your product's admin panel.
    "#{root_url}/admin/admin-panel/custom-domain"
  end

  def organization
    custom_domainable
  end
end

If the custom_domainable is not the Organization itself (eg. Site), update organization to traverse to the owning organization (eg. custom_domainable.organization).

4. Include the following module to your application's config/routes.rb file:

include NeetoCustomDomainsEngine::Routes::Draw

5. Define required routes.

# config/routes.rb
custom_domains_routes :acme

# routes/api.rb within the admin routes
custom_domains_routes :domain

6. Add frontend component. url should be the api to the custom domains controller.

import { CustomDomain as NeetoCustomDomainDashboard } from "@bigbinary/neeto-custom-domains-frontend";
import { BASE_API_V1_URL, SINGULAR } from "neetocommons/constants";
import HelpPopover from "neetomolecules/HelpPopover";
import { useTranslation } from "react-i18next";

import routes from "routes";
import { EVENTS } from "src/constants";
import { CUSTOM_DOMAIN_HELP_DOC_URL } from "src/constants/urls";

const CustomDomain = () => {
  const { t } = useTranslation();

  const breadcrumbs = [
    { link: routes.admin.settings.index, text: t("titles.settings") },
    {
      link: routes.admin.settings.customDomain,
      text: t("neetoCustomDomains.customDomain", SINGULAR),
    },
  ];

  const CUSTOM_DOMAIN_DNS_PROVIDER_HELP_DOCS = {
  cloudflare: {
    subdomain: `${PERMANENT_URL}/permanent-url-1`,
    rootDomain: `${PERMANENT_URL}/permanent-url-2`,
  },
  unknown: {
    subdomain: `${PERMANENT_URL}/permanent-url-3`,
    rootDomain: `${PERMANENT_URL}/permanent-url-4`,
  },
  namecheap: {
    subdomain: `${PERMANENT_URL}/permanent-url-5`,
    rootDomain: `${PERMANENT_URL}/permanent-url-6`,
  },
  hostinger: {
    subdomain: `${PERMANENT_URL}/permanent-url-7`,
    rootDomain: `${PERMANENT_URL}/permanent-url-8`,
  },
  digitalocean: {
    subdomain: `${PERMANENT_URL}/permanent-url-9`,
    rootDomain: `${PERMANENT_URL}/permanent-url-10`,
  },
  godaddy: {
    subdomain: `${PERMANENT_URL}/permanent-url-11`,
    rootDomain: `${PERMANENT_URL}/permanent-url-12`,
  },
  squarespace: {
    subdomain: `${PERMANENT_URL}/permanent-url-13`,
    rootDomain: `${PERMANENT_URL}/permanent-url-14`,
  },
  wix: {
    subdomain: `${PERMANENT_URL}/permanent-url-15`,
    rootDomain: `${PERMANENT_URL}/permanent-url-16`,
  },
  porkbun: {
    subdomain: `${PERMANENT_URL}/permanent-url-17`,
    rootDomain: `${PERMANENT_URL}/permanent-url-18`,
  },
  networksolutions: {
    subdomain: `${PERMANENT_URL}/permanent-url-19`,
    rootDomain: `${PERMANENT_URL}/permanent-url-20`,
  },
  aws: {
    subdomain: `${PERMANENT_URL}/permanent-url-21`,
    rootDomain: `${PERMANENT_URL}/permanent-url-22`,
  },
  strato: {
    subdomain: `${PERMANENT_URL}/permanent-url-23`,
    rootDomain: `${PERMANENT_URL}/permanent-url-24`,
  },
}

  return (
    <div className="w-full">
      <NeetoCustomDomainDashboard
        appName="appname" // Eg: `cal`, `form`
        dnsHelpDocs={CUSTOM_DOMAIN_DNS_PROVIDER_HELP_DOCS}
        helpDocUrl={CUSTOM_DOMAIN_HELP_DOC_URL}
        subdomainPlaceholder="subdomain-placeholder" // Eg: `schedule` for NeetoCal and `form` for NeetoForm
        url={`${BASE_URL}/custom-domains`}
        { ...{ breadcrumbs } }
      />
    </div>
  );
};

export default CustomDomain;

7. Mount the CustomDomain component at the desired path.

SEO: redirect to the custom domain and canonical URLs

Once a custom domain is active, public pages on the product subdomain should redirect to it, and canonical URLs should point to it.

1. Include NeetoCustomDomainsEngine::CanonicalHostRedirection in the public base controller only. Never include it in admin, API or auth controllers. Those must keep working on the subdomain, so a customer whose domain broke can still log in and fix it.
2. The concern reads the domainable from @organization. If the domainable is something else (eg: a Site), override the private method canonical_custom_domainable.
3. Use canonical_url for <link rel="canonical"> and og:url. It keeps ?page=N for pages beyond the first and drops every other query param.
4. Build sitemap and robots URLs from canonical_root_url(fallback), where the fallback is the subdomain base URL.

GET and HEAD requests on the subdomain get a 301 to the same path and query on the primary custom domain. The redirect only happens while the domain is active and has no redirection of its own. Otherwise the subdomain serves the page and canonical URLs fall back to the subdomain. These requests are never redirected: JSON requests, browser loads that are not a top-level page navigation (a Sec-Fetch-Dest other than document, such as iframes, fetch and XHR calls or images), signed-in users (so private content and draft previews keep working on the subdomain), and requests on any other custom domain of the same domainable. The 301 is cached privately for one hour.

Each redirect arms a liveness probe for domains with a stored certificate. If the redirected request does not arrive on the custom domain within a minute, the engine runs ReconcileCertificateJob for that domain. A domain that cannot be reached for over an hour is marked failed and the owner gets an email. A hit on the custom domain, or a probe, is trusted for six to seven hours, so each domain is probed at most once in that window.

ENV variables

For the working of this engine we need the following env variables.

LETS_ENCRYPT_PRIVATE_KEY: < For requesting SSL certificates >
LETS_ENCRYPT_DIRECTORY_URL: < For requesting SSL certificates >
LETS_ENCRYPT_APP_NAME: < For pushing SSL certificate and custom domains >
NEETO_DEPLOY_APP: < To identify in which platform the app is deployed NeetoDEploy/Heroku>
NEETO_DEPLOY_AUTH_TOKEN: <For pushing SSL certificate and custom domains>

Optional, staging only:

CUSTOM_DOMAIN_EDGE_CERTIFICATE_SUFFIX: < e.g. review.neetoautomation.com >

Hostnames one label under this suffix are activated without a DNS check or a certificate, because Cloudflare's wildcard certificate already serves them. It is read only when Rails.env.staging?, so setting it anywhere else has no effect.

Migrating existing domains to Cloudflare

Domains created before Cloudflare-for-SaaS was enabled have no route to registration — CloudflareValidationSyncJob is only enqueued when a domain is created, or when a DCV token is fetched. The backfill task is that route. Run it inside each product, one product at a time.

# Changes nothing. Shows what would be registered.
bundle exec rake neeto_custom_domains_engine:cloudflare:backfill_report

# Registers them.
bundle exec rake neeto_custom_domains_engine:cloudflare:backfill

It refuses to run unless NEETO_CUSTOM_DOMAINS_CERTIFICATE_BACKEND is dual or cloudflare and both CLOUDFLARE_SAAS_ZONE_ID and CLOUDFLARE_SAAS_API_TOKEN are set.

| variable | default | what it does | |---|---|---| | MAX_IN_FLIGHT | 100 | how many certificates may be validating at once | | LIMIT | none | stop after releasing this many in one run | | MAX_MINUTES | 120 | wall-clock budget before the run stops |

MAX_IN_FLIGHT is the one that matters. Registering costs a single API call per domain, but every domain waiting on validation polls Cloudflare roughly ten times per five minutes. Against a limit near 1,200 requests per five minutes that puts the ceiling around 120 certificates in flight, and the default leaves headroom. Raising it risks rate-limiting every product at once, because the limit is per account rather than per zone.

The task is safe to stop and re-run: a domain that already holds a cloudflare_hostname_id is skipped. Only active domains are registered — a failed domain has DNS that does not point at us, so registering it just churns against the CA. Domains still pending are picked up by a later run once they go active.

Only one backfill may run at a time; a second is refused via a Redis lock.

Registration is not a cutover. It leaves Let's Encrypt serving and Cloudflare idle alongside it. Traffic only moves when the domain's DNS starts pointing at a proxied hostname.

Instructions for Publishing

Consult the building and releasing packages guide for details on how to publish.

Integrations

• NeetoCal
• NeetoForm
• NeetoKb
• NeetoEngage
• NeetoSite
• NeetoRecord
• NeetoPublish
• NeetoCourse
• NeetoCode
• NeetoDesk
• NeetoQuiz
• NeetoPlanner
• NeetoInvoice
• NeetoChat
• NeetoRunner