Skip to main content

TLS Docker Support​

View as Markdown
FreeTeamsScaleEnterprise

Recording Testcases and Data Mocks Docker logo​

  1. To record test cases and data mocks, follow these steps in the root directory of your application. Ensure that you have the following prerequisites in place:
  • If you're running via docker-compose, ensure to include the <CONTAINER_NAME> under your application service in the docker-compose.yaml file like this.
  • You must run all of the containers on the same network when you're using docker run command (you can add your custom network name using --network flag in docker run command).
  • In your Docker Compose file, every container should run on the same network.
  • Docker_CMD_to_run_user_container refers to the Docker command for launching the application.
  • Add the required commands to your DockerFile as stated below.

  1. Trust is handled for you — no certificate to bake in.

    Keploy generates a fresh MITM certificate authority for each run and injects it, along with the matching trust environment variables, into your application container automatically (docker run, docker compose and --from-container). The CA's private key stays inside the Keploy agent and is never written anywhere your application container can read it.

    Older guides said to bake in a ca.crt

    Earlier versions of this page told you to ADD a ca.crt and source setup_ca.sh from a raw GitHub URL. Remove those lines. That recipe baked in a single static CA whose private key was public, and its setup_ca.sh overrode Keploy's injected trust (breaking interception for Node and Python requests apps). The URL now serves an inert placeholder so old images keep building, but you should drop the ADD/source lines and rely on the automatic injection above.

    Most runtimes (Go, Node, Python requests/httpx, curl, Java, .NET, Rust) trust Keploy's CA from the injected environment variables with no image change. A few libraries read only the OS trust store and ignore those variables — notably libcurl used as a library (PHP's curl extension, Guzzle), git, and wget/GnuTLS. If your app uses one of those, install the per-run CA into the image's store at startup from the volume Keploy mounts:

        # Only needed for apps that read the OS trust store directly (PHP curl, git, wget).
        RUN apt-get update && apt-get install -y ca-certificates
        # Install the per-run CA that Keploy mounts at /tmp/keploy-tls, then run the app.
        CMD ["/bin/bash", "-c", "cp /tmp/keploy-tls/keploy-ca.crt /usr/local/share/ca-certificates/keploy.crt 2>/dev/null; update-ca-certificates 2>/dev/null; <your app running command>"]

To capture test cases, Execute the following command within your application's root directory.

keploy record -c "Docker_CMD_to_run_user_container --network <network_name>" --container-name "<container_name>"

Make API calls using Postman , or cURL commands.

Keploy will capture the API calls you've conducted, generating test suites comprising test cases (KTests) and data mocks (KMocks) in YAML format.

Running Testcases​

To execute the test cases, follow these steps in the root directory of your application.

When using docker-compose to start the application, it's important to ensure that the --container-name parameter matches the container name in your docker-compose.yaml file.

keploy test -c "Docker_CMD_to_run_user_container --network <network_name>" --container-name "<container_name>" --delay 20

Voilà! 🧑🏻‍💻 We have the tests with data mocks running! 🐰🎉

You'll be able to see the test cases that ran with the results report on the console as well as locally in the testReport directory.

A client that pins its own CA​

A client that trusts only a CA file it names itself rejects the certificate Keploy answers its HTTPS calls with, because Keploy's per-run CA isn't in that file. Examples are Python requests with verify="/certs/ca.pem" and a Go client with its own RootCAs. Its call fails, and Keploy doesn't record it. keploy record says so when the recording ends, and names the test cases recorded while those calls failed:

WARN  2 TLS handshake(s) with keploy's proxy failed while this recording ran (a client that does not trust keploy's CA rejects keploy's certificate); those calls are not recorded  {"testCases": ["get-pinned-1", "get-pinned-2"], ...}

To record those calls, point the client at a file that holds Keploy's CA as well as its own while Keploy runs your application:

  • Docker and Docker Compose: Keploy mounts its per-run CA in your application container at /tmp/keploy-tls/keploy-ca.crt. Combine it with your own CA when the container starts, and point the client at the combined file:

    services:
      app:
        environment:
          PINNED_CA: /tmp/ca-with-keploy.pem
        command:
          [
            "/bin/sh",
            "-c",
            "cat /certs/ca.pem /tmp/keploy-tls/keploy-ca.crt > /tmp/ca-with-keploy.pem 2>/dev/null || cp /certs/ca.pem /tmp/ca-with-keploy.pem; exec python -u /app.py",
          ]
    requests.get(url, verify=os.environ.get("PINNED_CA", "/certs/ca.pem"))

    Outside Keploy the file doesn't exist, so the container falls back to your own CA.

  • Native: while Keploy runs your application, it sets SSL_CERT_FILE in the application's environment to a file that holds Keploy's per-run CA. Combine that file with your own CA in the command Keploy starts, such as a start script you run with keploy record -c "./start.sh":

    #!/bin/sh
    cat /certs/ca.pem "${SSL_CERT_FILE:-/dev/null}" > /tmp/ca-with-keploy.pem
    PINNED_CA=/tmp/ca-with-keploy.pem exec python -u app.py

    Outside Keploy, with SSL_CERT_FILE unset, the combined file holds only your own CA.

Removing Keploy's CA from a host​

For containerized runs there is nothing to clean up — the per-run CA lives in the agent container and goes away with it. On a native run (keploy record/test without Docker on Linux), Keploy installs its per-run CA into the host trust store for the duration of the run and removes it on exit.

If you ran an older keploy (which installed a static CA and never removed it), or a run was killed before it could clean up, remove the leftover CA with:

sudo keploy ca clean --fresh

This removes Keploy's CA from the system trust store, the JDK keystore and any leftover temp files, matched by fingerprint so your own certificates are left untouched.

  • Windows: the CA is added to your user's Root store (older elevated runs may have used the machine store). Remove it with certutil -user -delstore Root "Keploy MITM CA" (and, for a machine-store entry, the same command without -user from an elevated prompt). The retired static CA used the name My Custom CA.
  • macOS: native runs do not add anything to the system keychain (trust is set per process), so there is nothing to remove.