Configuring a test environment

The great people at Let's Encrypt wrote two nice tools to easily test ACME clients: Pebble and challtestsrv.

Pebble is a small test server that will act almost like ACME servers like Let's Encrypt. The major differences are:

• Pebble doesn't store data on disk: every time it's started, all the previously registered accounts, domains, certificates, ... are lost
• Pebble doesn't have any rate limits
• Pebble doesn't implement way to check certificate revocations (like OCSP).

challtestsrv can act like a DNS server and like a web server, and it's very lightweight and easy to configure.

Getting Pebble and challtestsrv

Both tools can run flawlessly under Linux, Mac and Windows. In order to get them:

• install Go
• open a terminal console and run this command:

  go get -u github.com/letsencrypt/pebble/...

In this document we'll use the GOPATH environment variable. If you don't configure it explicitly, you can replace its references here with the output of the go env GOPATH command (it should be $HOME/go on Linux/Mac, %USERPROFILE%\go on Windows).

Launching challtestsrv

The concrete5 ACME package will only require the DNS-related features of challtestsrv, so we can disable its HTTP and TLS related features.

So we can launch it with this command line:

# On Linux/Mac:
"%GOPATH/bin/pebble-challtestsrv" -http01 "" -https01 "" -tlsalpn01 ""
# On Windows:
"%GOPATH%\bin\pebble-challtestsrv.exe" -http01 "" -https01 "" -tlsalpn01 ""

By default, the DNS server will be available on the 8053 port. If you want to use another one (for example 9999), simply add this option: -dns01 ":9999"

Launching Pebble

First of all, you have to know the path of the GOPATH environment variable. You can determine it by launching go env GOPATH in a terminal console. From now on, we'll assume that it's /home/user/go (for Linux/Mac) or C:\Users\User\go (for Windows.

Next, you need to know the port that your test web server will be available at (here we suppose it's 10000).

Once you know all the above, you should create a JSON file (let's call it pebble.json) like this:

• for Linux/Mac:

  {
    "pebble": {
      "listenAddress": "0.0.0.0:14000",
      "managementListenAddress": "0.0.0.0:15000",
      "certificate": "/home/user/go/src/github.com/letsencrypt/pebble/test/certs/localhost/cert.pem",
      "privateKey": "/home/user/go/src/github.com/letsencrypt/pebble/test/certs/localhost/key.pem",
      "httpPort": 10000,
      "tlsPort": 5001,
      "ocspResponderURL": ""
    }
  }

• for Windows:

{
  "pebble": {
    "listenAddress": "0.0.0.0:14000",
    "managementListenAddress": "0.0.0.0:15000",
    "certificate": "C:\\Users\\User\\go\\src\\github.com\\letsencrypt\\pebble\\test\\certs\\localhost\\cert.pem",
    "privateKey": "C:\\Users\\User\\go\\src\\github.com\\letsencrypt\\pebble\\test\\certs\\localhost\\key.pem",
    "httpPort": 10000,
    "tlsPort": 5001,
    "ocspResponderURL": ""
  }
}

You can finally launch Pebble with this command:

# On Linux/Mac:
"%GOPATH/bin/pebble" -config "pebble.json" -dnsserver "127.0.0.1:8053"
# On Windows:
"%GOPATH%\bin\pebble.exe" -config "pebble.json" -dnsserver "127.0.0.1:8053"

Please remark that here we assume that challtestsrv has been launched with the default 8053 port. If you used another port, change the -dnsserver option accordingly.

Configuring the concrete5 ACME package

When adding the Pebble ACME server, you should adjust the Authorization ports to reflect the value of the httpPort of the pebble.json file.