neeto-custom-domains-engine

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

Contents

1. Development with Host application
   • Engine
     • Installation
     • Usage
2. Instructions for publishing

Development with Host application

Engine

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. Add this line to your application's config/routes.rb file:

mount NeetoCustomDomainsEngine::Engine => "/custom_domains"

4. Run migrations

rails neeto-custom-domains-engine:install:migrations
rails db:migrate

Usage

The steps below depend on the association that we use. In some cases, we need to attach multiple custom domains to a model, while in other cases, we only need a single custom domain. We have to make necessary configurations depending on this.

Let's say we have a "Site" model, and we want to publish our site on a custom domain.

Configure has_one association

The site only needs to be published in a single custom domain, so we chose has_one association.

1. Add association

class Site > ApplicationRecord
  has_one :custom_domain, as: :custom_domainable, class_name:   "NeetoCustomDomainsEngine::Domain", dependent: :destroy
end

2. Add controller

All common controller logic is extracted to the engine. However, we still need to load some records depending on the association that we use.

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

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

    def load_custom_domain!
      @custom_domain = @custom_domainable.custom_domain
    end
end

3. Add routes

include NeetoCustomDomainsEngine::Routes::Draw

scope module: :sites do
  custom_domains_routes(route: :custom_domain)
end

4. Add front-end component

import { CustomDomain } from "@bigbinary/neeto-molecules/CustomDomain";

For more info related to front-end component: https://github.com/bigbinary/neeto-molecules/blob/main/docs/components.md#customdomain

Configure has_many association

The site needs to be published in multiple custom domains, so we chose has_many association.

1. Add association

class Site > ApplicationRecord
  has_many :custom_domain, as: :custom_domainable, class_name: "NeetoCustomDomainsEngine::Domain", dependent: :destroy
end

2. Add controller

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

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

    def load_custom_domain!
      @custom_domain = @custom_domainable.custom_domains.find(params[:id])
    end
end

3. Add routes

include NeetoCustomDomainsEngine::Routes::Draw

scope module: :sites do
  custom_domains_routes(route: :custom_domain)
end

4. Add front-end component

import { CustomDomainDashBoard } from "@bigbinary/neeto-molecules/CustomDomainDashboard";

For more info related to front-end component: https://github.com/bigbinary/neeto-molecules/blob/main/docs/components.md#customdomainDashboard

Loading site from custom domain

Let's say we have attached the custom domain test.neeto.com to a site. Now, when the user tries to access test.neeto.com in the browser, we should display the corresponding site in the front-end. In order to achieve this, we need to load the site from the custom domain.

custom_domain = NeetoCustomDomainsEngine::Domain.find_by(hostname: params[:custom_domain])
if custom_domain.present?
  @published_site = custom_domain.custom_domainable.published_site
else
  site = Site.find_by! subdomain: params[:subdomain]
  @published_site = site.published_site
end

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_VALIDATION_DOMAIN_ACCESS_TOKEN: < For domain authentication>
LETS_ENCRYPT_VALIDATION_DOMAIN_ID: < For domain authentication>
LETS_ENCRYPT_VALIDATION_DOMAIN_NAME: < For domain authentication>
LETS_ENCRYPT_APP_NAME: < For pushing SSL certificate and custom domains >
HEROKU_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.