meu entulho querido


Wildcard subdomains on Dokku

The solution for making Dokku to make it accept my subdomain configuration (which is: to listen on all subdomains of a domain name such that each user registered at that domain get its own subdomain).

Where is $DOKKU_ROOT?

Stupid question, but maybe you’re like me and will take some precious time to discover it alone.

It is, by default, on /home/dokku (it is the default when you install from Digital Ocean, for example). I was searching on /root and /root/dokku for a long time.

This is important mainly because all tutorials and source code excerpts out there talk about $DOKKU_ROOT. Now that you know it you probably don’t even need the rest of this article.

Adding wildcard subdomains

In Heroku you would the following:

heroku domains:add '*' --app <app-name>

Dokku has a similar domains plugin, which you can use like the following:

dokku domains:add <app-name> ''

But you can’t do

dokku domains:add <app-name> '*'

Look at the source code for the domains plugin (this domains is a plugin that comes bundled in the default dokku installation):

It basically puts the domain you’re adding in a file called VHOSTS, inside $DOKKU_ROOT/$APP/, then reconfigures nginx. How it reconfigures nginx doesn’t matter, but in the end the end there is a nginx.conf file in that same folder. That file is what matters.

You don’t need to know anything abount nginx, you just need to know that the line

  server_name ;

Is what determines which domains your app will be listening for. You should add a wildcard domain there, but

  1. You can’t add *, nginx will not understand it. You need a regular expression (which needs to start with ~), so what you’ve got to do is add a domain named ~^(.*)\.main-domain\.com$
  2. You can’t add it directly in nginx.conf, since it will be recreated and modified by the domains plugin and who knows what else, so you just add ~^(.*)\.main-domain\.com$ to VHOSTS.

After doing that, do a dokku nginx:build-config <app-name> and check nginx.conf. Everything will be alright.

What if?

  • What happens if you do a dokku domains:add <app-name> '~^(.*)\.main-domain\.com$'? The domains plugin will not understand it and will ask you for a valid domain.
  • What happens if you do a dokku domains:add <app-name> '*'? Bad things. The * will be interpreted by the plugin code and it will add any other subdomains of that you had already registered to other apps.