Custom Domain Setup

Setting up a custom domain for your Dockit documentation site helps establish your brand identity and provides a professional appearance. This guide covers the complete process of configuring custom domains across different hosting platforms.

Overview

A custom domain allows you to serve your documentation from your own branded URL instead of the default hosting provider subdomain. For example:

• Default: your-docs.netlify.app or your-docs.vercel.app

• Custom: docs.yourcompany.com or help.yourcompany.com

Prerequisites

Before setting up a custom domain, ensure you have:

1. Domain ownership: You own or control the domain you want to use

2. DNS access: Ability to modify DNS records for your domain

3. Deployed site: Your Dockit site is already deployed and working

4. SSL certificate: HTTPS support (usually provided automatically)

Domain Configuration Options

Subdomain Setup (Recommended)

Using a subdomain is the most common and recommended approach:

Root Domain Setup

You can also use your root domain, though this requires additional considerations:

Path-based Setup

Serve documentation from a specific path:

Platform-Specific Setup

Netlify Configuration

Step 1: Add Custom Domain in Netlify

1. Go to your site’s Site Settings in Netlify dashboard

2. Navigate to Domain management → Custom domains

3. Click Add custom domain

4. Enter your domain (e.g., docs.yourcompany.com)

Step 2: Configure DNS Records

Add a CNAME record in your DNS provider:

Step 3: Enable HTTPS

Netlify automatically provisions SSL certificates through Let’s Encrypt:

1. Wait for DNS propagation (up to 24 hours)

2. SSL certificate will be automatically issued

3. Force HTTPS redirect in Site Settings → HTTPS

Step 4: Configure _redirects (Optional)

Create a \_redirects file in your public/ directory:

Vercel Configuration

Step 1: Add Domain in Vercel

1. Go to your project dashboard

2. Navigate to Settings → Domains

3. Enter your custom domain

4. Choose the deployment branch

Step 2: Configure DNS

For subdomains, add a CNAME record:

For root domains, add A records:

Step 3: Verify Domain

Vercel will automatically verify your domain and issue SSL certificates.

Step 4: Configure vercel.json

GitHub Pages Configuration

Step 1: Configure Repository Settings

1. Go to repository Settings → Pages

2. Select source (usually main branch)

3. Add custom domain in the Custom domain field

Step 2: Create CNAME File

Create a CNAME file in your repository root or public/ directory:

Step 3: Configure DNS

Add a CNAME record pointing to GitHub Pages:

Step 4: Enable HTTPS

GitHub Pages automatically provides SSL certificates for custom domains.

Firebase Hosting Configuration

Step 1: Configure firebase.json

Step 2: Add Custom Domain

Add domain in Firebase Console:

1. Go to Hosting section

2. Click Add custom domain

3. Follow the verification steps

Step 3: DNS Configuration

Add the provided DNS records from Firebase Console.

DNS Provider Examples

Cloudflare DNS

Additional Cloudflare settings:

• SSL/TLS: Full (strict)

• Always Use HTTPS: On

• Automatic HTTPS Rewrites: On

Google Domains

Namecheap DNS

Route 53 (AWS)

SSL Certificate Configuration

Automatic SSL (Recommended)

Most modern hosting platforms provide automatic SSL:

• Netlify: Let’s Encrypt (automatic)

• Vercel: Automatic SSL provisioning

• GitHub Pages: Automatic for custom domains

• Firebase: Google-managed certificates

Manual SSL Configuration

For advanced setups, you might need manual SSL configuration:

Advanced Configuration

Multiple Domains

Configure multiple domains for the same site:

Internationalization Domains

Set up different domains for different languages:

CDN Integration

Configure CDN for better performance:

Security Best Practices

HSTS Configuration

Enable HTTP Strict Transport Security:

Content Security Policy

Additional Security Headers

Performance Optimization

DNS Optimization

1. Use fast DNS providers: Cloudflare, Route 53, or Google DNS

2. Minimize DNS lookups: Reduce external resource dependencies

3. Enable DNS prefetching: \<link rel="dns-prefetch" href="//example.com"\>

Caching Strategy

Monitoring and Analytics

Domain Health Monitoring

Set up monitoring for your custom domain:

Analytics Configuration

Troubleshooting

Common Issues

DNS Propagation Delays

DNS changes can take up to 48 hours to fully propagate worldwide:

Online tools:

• whatsmydns.net

• dnschecker.org

SSL Certificate Issues

Common SSL problems and solutions:

1. Mixed content errors: Ensure all resources use HTTPS

2. Certificate mismatch: Verify domain names match certificate

3. Expired certificates: Set up auto-renewal

Redirect Loops

Prevent infinite redirects:

Performance Issues

Diagnose and fix performance problems:

Debug Tools

DNS Debugging

SSL Debugging

Migration Strategies

Zero-Downtime Migration

Plan for seamless domain migration:

1. Prepare new domain: Set up and test thoroughly

2. Update DNS with low TTL: Reduce propagation time

3. Monitor traffic: Watch for any issues

4. Implement redirects: Guide users to new domain

5. Update internal links: Change all references

6. Notify users: Communicate the change

Migration Checklist

• Domain ownership verified

• DNS records configured

• SSL certificate active

• Redirects implemented

• Internal links updated

• External references notified

• Analytics tracking updated

• SEO considerations addressed

• Monitoring alerts configured

• Rollback plan prepared

Best Practices

1. Choose meaningful subdomains: Use clear, descriptive names

2. Enable HTTPS everywhere: Never serve content over HTTP

3. Monitor domain health: Set up uptime monitoring

4. Plan for disasters: Have backup domains ready

5. Document your setup: Keep configuration records

6. Regular maintenance: Review and update configurations

7. Security first: Implement proper headers and policies

8. Performance matters: Optimize for speed and reliability

Conclusion

Setting up a custom domain for your Dockit documentation site enhances your brand presence and provides a professional experience for your users. Follow the platform-specific instructions, implement proper security measures, and monitor your domain’s health for the best results.

Remember to test thoroughly in a staging environment before making changes to production domains, and always have a rollback plan ready in case of issues.