Skip to main content

Domains

Defang helps you provision SSL certificates and expose your services to the internet. You can expose your services using Defang-hosted domains or bring your own custom domain with Defang BYOC. This page explains how to configure your services to be accessible from the public internet.

Defang-hosted Domains​

To make your service accessible from the public internet with Defang-hosted domains (under defang.app), you simply expose ports in your service definition.

Structure​

When you deploy a publicly accessible service, Defang automatically provides you with domain names to access it.

If you're deploying to the Defang Playground, you will receive:

Defang-hosted domain:

https://<username>-<service-name>--<port>.defang.dev

Sample Configuration​

services:
    # [...]
    serviceName:
        ports:
        - mode: ingress
          target: 3000
          protocol: http

Bring Your Own Domain​

You can also bring your own domain to a Defang project. This allows you to use your own domain name to access your services, and varies a little bit depending on your setup.

DNS Management Options​

When bringing your own domain, you have two main approaches:

Option 1: Using Your Existing DNS Provider (CloudFlare, Namecheap, etc.)​

If you are using Defang BYOC and do not have your domain's DNS hosted with your cloud provider, or if you are using the Defang Playground, you have two choices:

A. Point directly to your custom domain:

  1. Add the domainname to your service definition.
  2. Run defang compose up to deploy your project.
  3. Run defang cert generate to generate an SSL certificate. This command will provide instructions for where to point your domain's DNS before the certificate can be issued.
  4. Note: The infrastructure behind your domain (e.g., the load balancer) is recreated on every defang compose down + defang compose up, so you will need to update your DNS record and run defang cert generate again after each redeploy.

B. CNAME to your Defang-hosted domain (Recommended for frequent deployments):

If you frequently deploy and tear down your services (e.g., for staging environments), you can avoid reconfiguring your external DNS record each time:

  1. Keep the domainname set to your custom domain in your service definition — defang cert generate needs it to know which hostname to issue a certificate for.
  2. Run defang compose up to deploy your project.
  3. In your DNS provider, create a CNAME record pointing your custom domain to the defang.app domain Defang provides (e.g., service-name--port.project-name.username.defang.app). Unlike the load balancer's domain, this one stays the same across redeploys.
  4. Run defang cert generate to create the SSL certificate. Note: you'll still need to run this again after each defang compose up to recreate the certificate — but your CNAME record won't need to change.

:::tip Managing Multiple Environments Use the --project-name flag or the name: field in your Compose file to create separate environments. For example, a project named "hello" with --project-name hello-staging would create a separate deployment, allowing you to maintain both production and staging environments simultaneously. :::

Option 2: Using Route 53 (AWS) - Automatic DNS Management​

If you are using Defang BYOC and the DNS for your domain is hosted with your cloud provider (i.e. a Hosted Zone in Route 53, if you're using AWS), all you need to do is specify the domainname in your service definition, as in the example below.

Benefits of Route 53:

  • DNS records are automatically created and updated
  • SSL certificates are automatically provisioned and renewed
  • No need to run defang cert generate after each deployment
  • Ideal for environments that are frequently deployed and torn down
warning

For the time being, you can only use one domain per service. If you need to use multiple domains, please vote on this issue.

Sample Configuration​

services:
    # [...]
    serviceName:
        domainname: example.com
        ports:
        - mode: ingress
          target: 3000
          protocol: http

Current Support​

ProviderBYOD
AWS✅
Azure✅
DigitalOcean❌
GCP✅