Skip to content
brdz documentation

Hostnames

Hostnames allow you to serve your application from custom domains instead of default platform domains.

Overview

Section titled “Overview”

A hostname is:

  • A custom domain or subdomain (e.g., example.com, www.example.com)
  • Associated with a specific app
  • Used to serve your application’s current release
  • Configurable through DNS

Creating a Hostname

Section titled “Creating a Hostname”

Add a custom hostname to your current app:

Terminal window
brdz hostnames:create example.com

Requirements:

  • App context must be set
  • You must own the domain
  • Domain must be valid (RFC compliant)

Examples

Section titled “Examples”
Terminal window
# Add root domain
brdz hostnames:create example.com


# Add subdomain
brdz hostnames:create www.example.com


# Add API subdomain
brdz hostnames:create api.example.com


# Add environment-specific subdomain
brdz hostnames:create staging.example.com

Listing Hostnames

Section titled “Listing Hostnames”

View all hostnames for your current app:

Terminal window
brdz hostnames:list

Output example:

ID    Hostname              Created At
1     example.com           2025-01-18 10:30:00
2     www.example.com       2025-01-18 10:31:00
3     api.example.com       2025-01-18 14:20:00

DNS Configuration

Section titled “DNS Configuration”

After adding a hostname, you need to configure DNS to point to your application.

Using CNAME Records

Section titled “Using CNAME Records”

For subdomains (recommended):

www.example.com.    IN CNAME    your-app.brdz-platform.com.

Using A Records

Section titled “Using A Records”

For root domains:

example.com.        IN A        192.0.2.1

Using brdz DNS Management

Section titled “Using brdz DNS Management”

If your domain is managed through brdz DNS zones:

Terminal window
# Create a CNAME record
brdz dns:records:create www.example.com CNAME your-app.brdz-platform.com --zone <zone>


# Or create an A record
brdz dns:records:create example.com A 192.0.2.1 --zone <zone>

See DNS Management Guide for details.

SSL/TLS Certificates

Section titled “SSL/TLS Certificates”

SSL certificates are automatically provisioned for custom hostnames:

  • Certificates are issued via Let’s Encrypt
  • Automatic renewal before expiration
  • HTTPS is enforced by default
  • Certificate issuance may take a few minutes

Multiple Hostnames

Section titled “Multiple Hostnames”

You can add multiple hostnames to a single app:

Terminal window
# Add root domain
brdz hostnames:create example.com


# Add www subdomain
brdz hostnames:create www.example.com


# Add regional subdomain
brdz hostnames:create eu.example.com

All hostnames serve the same application and current release.

Hostname Best Practices

Section titled “Hostname Best Practices”
  1. Use www subdomain - Add both root and www for flexibility
  2. Verify DNS propagation - Check DNS before adding hostname
  3. Wait for SSL - Allow time for certificate issuance
  4. Use CNAME for subdomains - Easier to manage than A records
  5. Document hostnames - Keep track of which apps use which domains

Common Patterns

Section titled “Common Patterns”

Root and WWW

Section titled “Root and WWW”
Terminal window
brdz hostnames:create example.com
brdz hostnames:create www.example.com

Multiple Environments

Section titled “Multiple Environments”
Terminal window
# Production app
brdz ctx:use  # Select production app
brdz hostnames:create example.com


# Staging app
brdz ctx:use  # Select staging app
brdz hostnames:create staging.example.com

Multiple Services

Section titled “Multiple Services”
Terminal window
# Frontend app
brdz ctx:use  # Select frontend app
brdz hostnames:create www.example.com


# API app
brdz ctx:use  # Select api app
brdz hostnames:create api.example.com


# Docs app
brdz ctx:use  # Select docs app
brdz hostnames:create docs.example.com

Troubleshooting

Section titled “Troubleshooting”

DNS Not Resolving

Section titled “DNS Not Resolving”

If your hostname isn’t resolving:

  1. Check DNS configuration: dig example.com
  2. Wait for DNS propagation (up to 48 hours)
  3. Verify DNS records are correct
  4. Check for typos in CNAME/A records

SSL Certificate Issues

Section titled “SSL Certificate Issues”

If SSL certificate isn’t issued:

  1. Verify DNS is pointing to the correct target
  2. Wait up to 10 minutes for issuance
  3. Check domain validation is accessible
  4. Ensure no CAA records block Let’s Encrypt

Hostname Already Taken

Section titled “Hostname Already Taken”

If you can’t add a hostname:

  • Check if it’s already added to another app
  • Verify you own the domain
  • Ensure the hostname format is valid

Commands Reference

Section titled “Commands Reference”

hostnames:create <hostname>

Section titled “hostnames:create <hostname>”

Add a custom hostname to the current app.

Requirements:

  • App context must be set

Arguments:

  • hostname - Domain or subdomain (required)

Example:

Terminal window
brdz hostnames:create example.com

hostnames:list

Section titled “hostnames:list”

List all hostnames for the current app.

Requirements:

  • App context must be set

Example:

Terminal window
brdz hostnames:list
Section titled “Related Topics”

See Also

Section titled “See Also”