Boulder setup for HTTP-01 validations - FAKE_DNS!?


I'm working on a client library and all went fine until the point I'm trying to validate authorizations.
Boulder is setup on my machine (Win10, docker running, accounts / orders created successfully), the client also works from there.
I have an Apache 2.4 running that is setup to listen on all addresses on ports 80 and 5002 and has an alias for /.well-known/acme-challenge/ pointing to the directory my test-client puts all challenges in.

IP on local net:
Docker host seems to be
docker-compose.yml also notes and

Problem is that the validation agent can't connect to the domain / resolve it - I also can't get it when opening the docker shell and trying to cURL it.
I found several posts about changing "FAKE_DNS" in docker-compose.yml but most of them areolder than a year and none worked for me.

Already tried for FAKE_DNS (at checkout it came with


So - what do I need to set so any request from inside the container is routed to my host machine?

Thanks in advance.

I can't help with the Boulder question. But have you considered using Pebble for development instead?

Yes, tried that first - didn't work.
It doesn't respond with the exact set of details for e.g. account objects (when I remember correctly) so I would have been urgend to disable checks during development, that's not so cool.
Boulder seems to be great and easy for development - if only the DNS thing was explained in the docs...

For pebble and boulder, I modify the /etc/hosts file to point the domains to localhost.

For automated testing, here is what my client does:

And this is what I add - basically, each test gets it's own hosts so there are no errors from overlap:

1 Like

This doesn't seem to help, when running the docker shell a request to (or :5002) results in a "connection refused", same for the other IPs and
The only thing that is reachable is port 4001, the directory index.
Maybe it's because I'm running Windows.

$> curl
{ "keyChange": "", "meta": { "caaIdentities": [ "happy-hacker-ca.invalid" ], "termsOfService": "https://boulder:4431/terms/v7", "website": "" }, "newAccount": "", "newNonce": "", "newOrder": "", "revokeCert": "", "v83dO1bovhA": "" }

$> curl
curl: (7) Failed to connect to port 5002: Connection refused

Oh, that's a different problem. My solution is for routing DNS back to the local machine. In your case, I believe you need to configure your containers and host to map ports between one another.

That's what I'm looking for but I don't know how to do that.
I'm using the docker container download from Github, so basically I just called "docker-compose up" and all was working, just this DNS stuff get's me mad.

It's hard to tell exactly what is going on in your situation. If I were you, I would research "mapping ports docker".

These 2 lines suggest you do not have an issue with DNS, but the port permissions/mappings:

works $> curl
fails  $> curl

I would recommend not trying to route the challenges from inside the docker container outside, or fiddle with any port forwarding to start with in client development. When running boulder from docker it also spins up this inside the containers: GitHub - letsencrypt/challtestsrv: Small TEST-ONLY server for mock DNS & responding to HTTP-01, DNS-01, and TLS-ALPN-01 ACME challenges. (IIRC this was originally part of pebble and was spun out into it's own repo so if you look at any of the python eg test/ it is referred to as pebble-challtestserv)

So for initial development I'd recommend sending a post request to port 8055 to the /add-http01 endpoint something along the lines of,

curl -X POST -H "Content-Type: application/json" \
-d '{"Token":"AUTH_TOKEN","Content":"AUTH_CONTENT"}' \

Where AUTH_TOKEN is the challenge token (ie, the filename you'd save in .well-known/acme-challenge/FILENAME) and AUTH_CONTENT is the challenge key authorisation. I can't test if that is exactly the correct json/path (it might just be /add-http), but if you dive into the challtestserv code or look at other clients that are using it (my own client does this in testing here onwards), or even the integration tests in boulder, it should point you in the right direction.

In development, the method of fulfilling the challenges is really a little out of scope of the client directly, so I'd recommend just using this initially to get the end to end process working. Once you get it working with the challtestsrv then you can look at changing the DNS resolver to something outside of the docker container, or just testing against the staging server with a real domain (or something like an ngrok domain).

That said, the FAKE_DNS should work, but you'd want to point it to your development computer's local IP address so boulder will connect to your running apache instance outside of the docker networks. How exactly did you try changing the FAKE_DNS ?

I changed the docker-compose.yml and re-ran docker-compose up

I don't know what I've done else than before but hooray, I'm validating challenges :smiley:
After removing the whole setup and checking out a fresh copy of the sources the steps were now:

  • set FAKE_DNS to
  • add a file:test/config/hosts.txt
  • modify test/ and add:
    SCRIPTPATH="$( cd -- "$(dirname "$0")" >/dev/null 2>&1 ; pwd -P )" cat $SCRIPTPATH/config/hosts.txt >> /etc/hosts

So in the end it's as @jvanasco said, requires a bit of manual labor but hey, that's OK as I only have a few test-domains before testing against staging at LE.

Thanks to all for your help!

1 Like

This topic was automatically closed 30 days after the last reply. New replies are no longer allowed.