Custom TLS certificates

Background

LocalStack sometimes performs on-demand fetching of resources from the public internet. This requires that LocalStack is able to access public URLs. If there is a proxy server in your network that uses a non-standard TLS certificate, LocalStack will not be able to download any files on demand. You may see errors in the logs relating to TLS such as “unable to get local issuer certificate”.

There are two options when running LocalStack:

1. creating a custom Docker image or
2. using init hooks

They all can be summarised as:

1. get your proxy’s custom certificate into the system certificate store, and
2. configure requests to use the custom certificate,
3. configure curl to use the custom certificate, and
4. configure node.js to use the custom certificate.

Creating a custom docker image

If you run LocalStack in a docker container (which includes using the CLI, docker, docker-compose, or helm), to include a custom TLS root certificate a new docker image should be created.

Create a Dockerfile containing the following commands:

FROM localstack/localstack:latest
# or if using the pro image:
FROM localstack/localstack-pro:latest

COPY <your custom certificate.crt> /usr/local/share/ca-certificates/cert-bundle.crt
RUN update-ca-certificates
ENV CURL_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt
ENV REQUESTS_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt
ENV NODE_EXTRA_CA_CERTS=/etc/ssl/certs/ca-certificates.crt

and build the image:

docker build -t <image name> .

Tip

Certificate files must end in .crt to be included in the system certificate store. If your certificate file ends with .pem, you can rename it to end in .crt.

Starting LocalStack with the custom image

LocalStack now needs to be configured to use this custom image. The workflow is different depending on how you start localstack.

CLI

IMAGE_NAME=<image name> localstack start

Docker

docker run <docker arguments> <image name>

docker-compose.yml

services:
  localstack:
    image: <image name>
    # the rest of your configuration

Custom TLS certificates with init hooks

It is recommended to create a boot init hook. Create a directory on your local system that includes

• the certificate you wish to copy, and
• the following shell script:

#!/bin/bash

set -euo pipefail

cp /etc/localstack/init/boot.d/<your certificate file>.crt /usr/local/share/ca-certificates
update-ca-certificates

Then run LocalStack with the environment variables

• REQUESTS_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt, and
• CURL_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt, and
• NODE_EXTRA_CA_CERTS=/etc/ssl/certs/ca-certificates.crt

and follow the instructions fn the init hooks documentation for configuring LocalStack to use the hook directory as a boot hook.