github
/
acme4j
mirror of https://github.com/shred/acme4j
1
0
Fork 0
Code Issues Releases Wiki Activity

Adapt documentation about integration tests

pull/81/head
Richard Körber 2019-02-26 17:36:46 +01:00
parent 9941de6fc9
commit 55afe7697f
No known key found for this signature in database
GPG Key ID: AAB9FD19C78AA3E0
1 changed files with 11 additions and 16 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

27
src/site/markdown/development/testing.md
View File

@ -4,40 +4,35 @@
_acme4j_ provides a number of integration tests. These tests are _not_ executed by maven by default, as they require Docker on the build machine.
To run them, install Docker and make it available to your user. Then invoke `mvn -Pci verify` to run the integration tests. The test will build images of the current [Pebble ACME test server](https://github.com/letsencrypt/pebble), and an internal test server that provides a configurable HTTP and DNS server for Pebble.
To run them, install Docker and make it available to your user. Then invoke `mvn -Pci verify` to run the integration tests.
If you change into the `acme-it` project directory, you can also build, start and stop the test servers with `mvn docker:build`, `mvn docker:start` and `mvn docker:stop`, respectively. While the test servers are running, you can also run the integration tests in your IDE. `mvn docker:remove` finally removes the test server images.
The integration tests use the [latest docker image](https://hub.docker.com/r/letsencrypt/pebble) of the [Pebble ACME test server](https://github.com/letsencrypt/pebble) in a container named _pebble_. A second docker container named _bammbamm_ uses [pebble-challtestsrv](https://hub.docker.com/r/letsencrypt/pebble-challtestsrv) as a test server. Pebble connects to this test server for resolving domain names and for the verification of challenges.
## BammBamm
If you change into the `acme-it` module's directory, you can also build, start and stop the test servers with `mvn docker:build`, `mvn docker:start` and `mvn docker:stop`, respectively. While the test servers are running, you can run the integration tests in your IDE. `mvn docker:remove` finally removes the test server images.
The `acme4j-it` module contains a small and very simple test server called _BammBamm_, which can be used to verify challenges. In the default configuration, it uses these ports:
If you like to change the default configuration of the integration tests (e.g. because you are running _pebble_ and _pebble-challtestsrv_ instances on a dedicated test server), you can do so by changing these system properties:
* 14001: Provides a simple REST-like interface for adding and removing challenge tokens and DNS records. This port is exposed.
* 53 (UDP): A simple DNS server for resolving test domain names, and providing `TXT` records for `dns-01` challenges.
* 5001: A simple TLS-ALPN server that responds with certificates for `tls-alpn-01` challenges.
* 5002: A simple HTTP server that responds with tokens for `http-01` challenges.
To run this server, you can use the Docker image mentioned above. You could also run the server directly, but since the DNS server is listening on a privileged port, it would need to be reconfigured first. Also, if you run BammBamm with OpenJDK 8, make sure to [add the correct `alpn-boot.jar` version to your boot classpath](https://www.eclipse.org/jetty/documentation/9.4.x/alpn-chapter.html#alpn-versions) in order to use the TLS-ALPN server.
The `BammBammClient` class can be used to set the challenge responses and DNS records via the REST interface on port 14001.
* `pebbleHost`: Host name of the pebble server. Default: `localhost`
* `pebblePort`: Port the pebble server is listening on. Default: 14000
* `bammbammUrl`: URI of the _pebble-challtestsrv_ to connect to. Default: `http://localhost:8055`
<div class="alert alert-danger" role="alert">
Do not use _BammBamm_ in production environments! It has its main focus on simplicity, and is only meant as a server for integration test purposes. It is neither hardened, nor feature complete.
_pebble-challtestsrv_ is meant for testing purposes only. Only use it in secured testing environments. The server is neither hardened, nor does it offer any kind of authentication.
</div>
## Boulder
It is also possible to run some tests against the [Boulder](https://github.com/letsencrypt/boulder) ACME server, but the setup is a little tricky.
First, build and start the integration test Docker servers as [explained above](#Integration_Tests). When the servers are started, find out the IP address of the _BammBamm_ server:
First, build and start the integration test Docker containers as [explained above](#Integration_Tests). When the servers are started, find out the IP address of the _bammbamm_ server:
```bash
docker inspect bammbamm -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}'
```
Now set up a Docker instance of Boulder. Follow the instructions in the [Boulder README](https://github.com/letsencrypt/boulder#quickstart). When you are ready to start it, set the `FAKE_DNS` env variable to the IP address of _BammBamm_ you have found before.
Now set up a Docker instance of Boulder. Follow the instructions in the [Boulder README](https://github.com/letsencrypt/boulder#quickstart). When you are ready to start it, set the `FAKE_DNS` env variable to the IP address of _bammbamm_ you have found before.
The Boulder integration tests can now be run with `mvn -P boulder verify`.
For a local Boulder installation, just make sure that `FAKE_DNS` is set to `127.0.0.1`. You'll also need to expose the ports 5001 and 5002 of _BammBamm_ by changing the `acme4j-it/pom.xml` accordingly.
For a local Boulder installation, just make sure that `FAKE_DNS` is set to `127.0.0.1`. You'll also need to expose the ports 5001 and 5002 of _bammbamm_ by changing the `acme4j-it/pom.xml` accordingly.