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
  has_many :custom_domains, as: :custom_domainable, class_name:   "NeetoCustomDomainsEngine::Domain", dependent: :destroy

  # Optional
  def primary_custom_domain
    custom_domains&.where.missing(:redirection)&.first
  end
end

# If custom domain is associated to other resources (eg: Site)
class Site > ApplicationRecord
  has_many :custom_domains, as: :custom_domainable, class_name:   "NeetoCustomDomainsEngine::Domain", dependent: :destroy

  # Optional
  def primary_custom_domain
    custom_domains&.where.missing(:redirection)&.first
  end
end

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.

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>

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