Domain System

A Railway-focused skill for managing domains — adding generated Railway subdomains, configuring custom domains with DNS, and removing domain assignments from Railway services. Domain System handles the complete domain lifecycle from initial assignment through DNS verification.

When to Use This Skill

Choose Domain System when:

• Adding a Railway-generated subdomain to expose a service publicly
• Configuring a custom domain with proper DNS records
• Troubleshooting domain verification or SSL certificate issues
• Removing domain assignments from Railway services

Consider alternatives when:

• Managing DNS records at the registrar level (use your DNS provider's interface)
• Setting up CDN or edge caching (use Cloudflare, Fastly, etc.)
• Configuring domain routing for non-Railway services

Quick Start

Copy
claude "Add a domain to my Railway service"

Copy
# Generate a Railway subdomain (*.up.railway.app)
railway domain

# Add a custom domain
railway domain --set myapp.example.com

# View current domain assignments
railway status

Copy
## DNS Configuration for Custom Domains

### For root domain (example.com):
| Type | Name | Value |
|------|------|-------|
| CNAME | @ | <your-service>.up.railway.app |

### For subdomain (app.example.com):
| Type | Name | Value |
|------|------|-------|
| CNAME | app | <your-service>.up.railway.app |

Note: Some DNS providers don't support CNAME on root domains.
Use an ALIAS or ANAME record if available, or use a subdomain.

Core Concepts

Domain Types

Type	Format	SSL	DNS Required
Railway Subdomain	*.up.railway.app	Auto (included)	No
Custom Subdomain	app.example.com	Auto (Let's Encrypt)	CNAME record
Custom Root Domain	example.com	Auto (Let's Encrypt)	ALIAS/ANAME

SSL Certificate Lifecycle

1. Domain added to Railway
2. DNS verification check (CNAME must point to Railway)
3. Let's Encrypt challenge initiated
4. Certificate issued (usually 2-5 minutes)
5. Auto-renewal before expiration (90-day cycle)

Multiple Domains per Service

Copy
# Add primary domain
railway domain --set app.example.com

# Add additional domain (redirect or serve same content)
railway domain --set www.example.com

# Both domains serve the same Railway service
# Configure redirects in your application if needed

Configuration

Parameter	Description	Default
domain_type	Railway subdomain or custom	railway
custom_domain	Your custom domain name	None
force_https	Redirect HTTP to HTTPS	true
www_redirect	Redirect www to root (or vice versa)	false
dns_provider	Your DNS registrar for instructions	generic

Best Practices

1. Start with a Railway subdomain for testing. Before configuring custom domains and DNS, verify your service works correctly on a Railway-generated subdomain. This eliminates DNS as a variable when debugging deployment issues.

2. Use subdomains instead of root domains when possible. CNAME records on root domains are not universally supported. Using app.example.com with a standard CNAME is more reliable than example.com which requires ALIAS/ANAME support from your DNS provider.

3. Lower DNS TTL before migration. If you're pointing an existing domain to Railway, reduce the TTL to 60 seconds a day before the switch. This ensures the change propagates quickly. Raise it back to 3600+ after verification.

4. Verify SSL certificate issuance. After adding a custom domain, wait 5-10 minutes and check that HTTPS works. If SSL doesn't provision, the DNS CNAME likely hasn't propagated — use dig or nslookup to verify the record points to Railway.

5. Set up both root and www domains. Configure both example.com and www.example.com to point to your Railway service. Handle the redirect (www → root or root → www) in your application code to avoid duplicate content issues.

Common Issues

SSL certificate not provisioning. The CNAME record must point to your Railway service's .up.railway.app hostname. Verify with dig app.example.com CNAME — if it returns a different target, update the DNS record. Certificate issuance can take up to 10 minutes after DNS propagation.

Custom domain returns "DNS not configured." Railway checks DNS records when you add a custom domain. If the CNAME hasn't propagated yet, the check fails. Wait for DNS propagation (up to 48 hours for some providers, usually minutes) and Railway will automatically retry verification.

Root domain CNAME doesn't work. Many DNS providers (like GoDaddy, Namecheap) don't support CNAME on the zone apex. Options: use Cloudflare (supports CNAME flattening), use a provider that supports ALIAS/ANAME records, or use a subdomain like app.example.com instead.