Skip to main content

​
Overview

The Domain resource manages DNS infrastructure using BIND zone files as the primary interface. It creates Route53 hosted zones, DNS records, ACM certificates, and cross-account delegation roles.

​
Quick Start

# Scaffold a new domain
fjall domain create example.com

# Edit the zone file
# fjall/domains/example.com/zone.bind

# Deploy to AWS
fjall domain deploy example.com

​
Zone File Format

Configure domains via standard BIND zone files with Fjall extensions: 
$ORIGIN example.com.
$TTL 300

; Request an ACM certificate
$FJALL-CERT example.com *.example.com

; DNS records
@                        IN A 1.2.3.4
www                      IN CNAME example.com
mail                     IN MX 10 mail.example.com
@                        IN TXT "v=spf1 include:_spf.google.com ~all"

​
Fjall Extensions

​
$FJALL-CERT: ACM Certificate

Request an ACM certificate with automatic DNS validation: 
; Single domain
$FJALL-CERT example.com

; With wildcard SAN
$FJALL-CERT example.com *.example.com

; Multiple SANs
$FJALL-CERT example.com *.example.com api.example.com

​
$FJALL-DELEGATE: Cross-Account Delegation

Delegate a subdomain to another AWS account: 
; Manual delegation
$FJALL-DELEGATE staging 123456789012

; Auto-delegation (created during organisation deploy)
$FJALL-DELEGATE staging 123456789012 ; auto

​
ALIAS: Application Binding

Point DNS records to Fjall-managed applications: 
; Route to ECS application
@                        IN A ALIAS fjall:ecs:web

; Route to CloudFront distribution
cdn                      IN A ALIAS fjall:cdn:web-cdn

; Route to S3 website
static                   IN A ALIAS fjall:s3:web-static

​
Supported Record Types

TypeExample
A@ IN A 1.2.3.4
AAAA@ IN AAAA 2001:db8::1
CNAMEwww IN CNAME example.com
MX@ IN MX 10 mail.example.com
TXT@ IN TXT "v=spf1 ..."
NSsub IN NS ns1.other.com
SRV_sip._tcp IN SRV 10 60 5060 sip.example.com
CAA@ IN CAA 0 issue "letsencrypt.org"

​
CLI Commands

The fjall domain command groups every domain operation: create, deploy, verify, export, list, import, eject.

​
Create

# Standard domain (scaffolds a Route53 hosted zone)
fjall domain create example.com

# Reuse an existing hosted zone
fjall domain create example.com --hosted-zone-id Z1234567890

​
Deploy

<domain> is required. Deploy each domain by name: 
fjall domain deploy example.com

​
Verify

Check DNS propagation and nameserver delegation: 
fjall domain verify example.com
Output: 
Domain: example.com
Delegated to Route53: Yes
Nameservers:
  ns-1234.awsdns-01.org
  ns-5678.awsdns-02.co.uk
Pass --show-delegation to print registrar-style delegation instructions instead (requires a prior successful deploy).

​
Export

Export live Route53 records to a local zone file: 
fjall domain export example.com

​
Import

fjall domain import is not yet available. The end-to-end import flow is still in development. To bring an existing domain under Fjall management today, scaffold it with fjall domain create and reuse the live hosted zone via --hosted-zone-id.

​
List

fjall domain list

​
Organisation Integration

Domains deploy automatically during fjall deploy organisation: 
Platform → Domains → Accounts
Apex domains deploy sequentially (delegation roles must exist first), then subdomain domains deploy in parallel.

​
Configuration

Fjall tracks managed domains in fjall-config.json under the domains field: 
{
  "domains": [
    {
      "name": "example.com",
      "type": "apex"
    },
    {
      "name": "staging.example.com",
      "type": "delegated",
      "parentDomain": "example.com",
      "account": "123456789012"
    }
  ]
}
Each entry is { name, type: "apex" | "delegated", parentDomain?, account? }. fjall-config.json holds only two fields, domains and activeTarget. Account, region, and authentication data live in your organisation config, which the CLI fetches from the Fjall API.

​
Application Binding

When Fjall manages a domain, application stacks reference the domain’s hosted zone and certificate via CloudFormation cross-stack exports. This binding is automatic when an application’s domain matches a managed domain. The block below is illustrative, the wiring happens for you during deploy: 
// In your app's infrastructure.ts, generated automatically
// when the app has a domain that matches a managed domain
ComputeFactory.build("Web", {
  type: "ecs",
  domain: "api.example.com",
  managedDomain: {
    hostedZoneIdExport: "example-com-hosted-zone-id",
    certificateArnExport: "example-com-certificate-arn",
    zoneName: "example.com",
  },
});

​
External DNS Registrar

For domains registered outside AWS, point your registrar’s nameservers to Route53:
  1. Run fjall domain create example.com
  2. Run fjall domain deploy example.com
  3. Run fjall domain verify example.com to read the nameservers
  4. Update your registrar’s NS records to point to the Route53 nameservers
For subdomain-only delegation, create NS records at your registrar for the specific subdomain.

​
File Structure

fjall/domains/example.com/
  zone.bind              # BIND zone file (edit this)
  infrastructure.ts      # Generated CDK code
  package.json           # CDK dependencies
  cdk.json               # CDK configuration
  tsconfig.json          # TypeScript configuration

​
Next Steps

Load Balancer

Route traffic to your applications behind an AWS load balancer.

VPC

Configure VPCs, subnets, and routing for your AWS infrastructure.

ECS Cluster

Run containerised applications on ECS behind your domain.

Deploy

Ship your domains and applications to AWS with the Fjall CLI.