Setting Up Coolify with a Subdomain Wildcard

2025-05-18

Coolify is a self-hosted, open-source platform that runs on your server and helps speed up deployment. Think of it like a selfhosted version of heroku, for your VPS. It supports deploying all solutions in your toolkit from apps to db's to open source docker images via its library (posthog, n8n, plausible, etc.).

Why Use a Wildcard Subdomain?

A wildcard subdomain (e.g., *.example.com) allows you to route subdomains to your server. This is useful to map multiple resources under the same domain in a clean way. You can also use it to host your frontend on the root domain and your api on api.example.com, while using the same server (or cluster).

Steps to Set Up

1. Configure DNS

  • Go to your DNS provider.
  • Add a new A record for your wildcard subdomain:
    • Host/Name: *.api.example.com (or just * if you want all subdomains)
    • Value: Your Coolify server's public IP address
  • Save the record. DNS changes may take a few minutes to propagate.
  • While waiting, setup your AAAA record to point to your server's ipv6 address

2. Setup Proxy

  • Set the wildcard domain to your root, leave everything else as default here & save
  • Go to the proxy tab and add your DNS provider env file based on this - https://doc.traefik.io/traefik/https/acme/#providers
  • Make sure to set your acme.dnschallenge.provider to your provider
  • In labels, add your domain and subdomain
      - traefik.http.routers.traefik.tls.domains[0].main=example.com
      - traefik.http.routers.traefik.tls.domains[0].sans=*.example.com

3. Set Up Your Resources

  • On your coolify dashboard, go to your application (resource).
  • Fill in your domain (it can be a comma separated value of many domains or subdomains)
  • Save (don't click on Generate Domain)
  • Redeploy or restart your resource.

4. Deploy and Test

  • Try accessing it via any subdomain, e.g., api.example.com or <COMMIT_HASH>.api.example.com.
  • Setup http auth on preview branches to not let them get indexed by crawlers
  • You can setup a subdomain for your coolify console also

Common Issues

  • If you face SSL related errors like ERR_CERT_AUTHORITY_INVALID
    • On your proxy configuration, go to advanced
    • Under CA SSL Certificate, Regenerate Certificate
  • If you don't know the errors, go to Servers -> Proxy -> Logs
  • If you face this error - Router uses a nonexistent certificate resolver
    • Check the logs for a reason, scroll to the top
    • If the error is permission related, connext to the server via the terminal tab
    • Run this command 
        sudo chmod 600 /data/coolify/proxy/acme.json

Your domains are now setup correctly, restart the server or restart the proxy then all services to have the new changes reflect. If there are different errors you see, feel free to reach out. I have only documented the errors I faced across multiple setups across providers, and skipped the ones that didn't occur often.