Custom Domains

Use your own domain for environment access instead of the default *.teabar.dev. Custom domains provide a professional, branded experience for participants.

Domain Levels

Organization-Level Domain

Set a custom domain for all environments in your organization.

Step 1: Configure Domain in Teabar

teactl org domain set labs.acme.com

Step 2: Add DNS Records

Add a wildcard CNAME record pointing to Teabar’s gateway:

*.labs.acme.com  CNAME  acme.gateway.teabar.dev

Or if your DNS provider doesn’t support wildcard CNAME, add individual records:

*.march-workshop.labs.acme.com  CNAME  acme.gateway.teabar.dev
*.april-training.labs.acme.com  CNAME  acme.gateway.teabar.dev

Step 3: Verify Domain

teactl org domain verify labs.acme.com

Teabar verifies:

1. DNS records are correctly configured
2. Domain resolves to Teabar gateway
3. No conflicts with existing domains

Result

Your environments are now accessible at:

terminal.march-workshop.labs.acme.com
gitlab.march-workshop.labs.acme.com
argocd.march-workshop.labs.acme.com

Environment-Level Domain

Set a custom domain for a specific environment.

Step 1: Configure Domain

teactl env domain set my-workshop march.acme.com

Step 2: Add DNS Records

*.march.acme.com  CNAME  my-workshop.acme.gateway.teabar.dev

Step 3: Verify Domain

teactl env domain verify my-workshop march.acme.com

Result

Your environment is accessible at:

terminal.march.acme.com
gitlab.march.acme.com
argocd.march.acme.com

TLS Certificates

Automatic Certificates (Default)

Teabar automatically provisions Let’s Encrypt certificates:

# Check certificate status
teactl org domain cert status labs.acme.com

Output:

Domain: labs.acme.com
Type: Let's Encrypt (automatic)
Status: Active
Expires: 2024-06-15
Auto-renewal: Enabled

Custom Certificates

Upload your own certificate for specific requirements:

teactl org domain cert set labs.acme.com 
  --cert /path/to/certificate.pem 
  --key /path/to/private-key.pem 
  --ca /path/to/ca-chain.pem  # Optional CA chain

Certificate Requirements

Renewing Custom Certificates

# Check expiration
teactl org domain cert status labs.acme.com

# Update certificate
teactl org domain cert set labs.acme.com 
  --cert /path/to/new-certificate.pem 
  --key /path/to/new-private-key.pem

DNS Configuration

Wildcard CNAME (Recommended)

The simplest configuration:

*.labs.acme.com  CNAME  acme.gateway.teabar.dev

Individual CNAMEs

If your DNS provider doesn’t support wildcard CNAMEs:

terminal.march-workshop.labs.acme.com  CNAME  acme.gateway.teabar.dev
gitlab.march-workshop.labs.acme.com    CNAME  acme.gateway.teabar.dev
argocd.march-workshop.labs.acme.com    CNAME  acme.gateway.teabar.dev
ide.march-workshop.labs.acme.com       CNAME  acme.gateway.teabar.dev

A Records (Not Recommended)

If you must use A records, point to Teabar’s gateway IPs:

# Get current gateway IPs
teactl org domain gateway-ips

*.labs.acme.com  A  203.0.113.10
*.labs.acme.com  A  203.0.113.11

Domain Verification

Verification Methods

Teabar supports multiple verification methods:

teactl org domain set labs.acme.com

Add this DNS record to verify domain ownership:

_teabar-verify.labs.acme.com  TXT  "teabar-verification=abc123xyz"

Then run: teactl org domain verify labs.acme.com

Verification Status

teactl org domain status labs.acme.com

Output:

Domain: labs.acme.com
Status: Verified
DNS Records: Configured
Certificate: Active (Let's Encrypt)
Environments: 5 using this domain

Multiple Domains

Organizations can configure multiple custom domains:

# Add domains
teactl org domain set labs.acme.com
teactl org domain set training.acme.com
teactl org domain set workshops.acme-partner.com

# List domains
teactl org domain list

Output:

DOMAIN                       STATUS      CERTIFICATE    ENVIRONMENTS
labs.acme.com               verified    active         12
training.acme.com           verified    active         5
workshops.acme-partner.com  pending     pending        0

Assign Domains to Environments

# Use specific domain for environment
teactl env domain set my-workshop --use labs.acme.com

# Or in blueprint
spec:
  infrastructure:
    domain: labs.acme.com

URL Structure

With Organization Domain

labs.acme.com (organization domain)

Environment: march-workshop

URLs:
  terminal.march-workshop.labs.acme.com
  gitlab.march-workshop.labs.acme.com
  argocd.march-workshop.labs.acme.com
  
Participant URLs:
  march-workshop.labs.acme.com/participant/p1/terminal

With Environment Domain

march.acme.com (environment domain)

URLs:
  terminal.march.acme.com
  gitlab.march.acme.com
  argocd.march.acme.com
  
Participant URLs:
  march.acme.com/participant/p1/terminal

Subdomain Configuration

Default Subdomains

These subdomains are automatically configured:

Custom Service Subdomains

Add custom subdomains for your services:

spec:
  access:
    services:
      - name: my-app
        subdomain: app
        targetPort: 8080
        
      - name: api
        subdomain: api
        targetPort: 3000

Results in:

app.march-workshop.labs.acme.com → my-app:8080
api.march-workshop.labs.acme.com → api:3000

Removing Domains

# Remove organization domain
teactl org domain remove labs.acme.com

# Remove environment domain
teactl env domain remove my-workshop

Troubleshooting

Domain Not Resolving

1. Check DNS propagation: DNS changes can take up to 48 hours

# Check DNS resolution
dig +short terminal.march-workshop.labs.acme.com

2. Verify CNAME target: Should point to <org>.gateway.teabar.dev

dig CNAME terminal.march-workshop.labs.acme.com

Certificate Errors

1. Check certificate status:

teactl org domain cert status labs.acme.com

2. Force certificate renewal:

teactl org domain cert renew labs.acme.com

3. Check for CAA records: CAA records can block Let’s Encrypt

dig CAA acme.com

Verification Failed

1. Check TXT record:

dig TXT _teabar-verify.labs.acme.com

2. Wait for DNS propagation: Try again in 15 minutes

3. Try alternative method: Use CNAME or HTTP verification

View Domain Logs

teactl org domain logs labs.acme.com

Provider-Specific Instructions

Next Steps