API Self-Hosted v3 – Using a private or internal CA

This guide explains how to make Draftable API Self-Hosted v3 trust a private or internal certificate authority (CA). There are two distinct situations where you need this, and they have different symptoms. Read the one that matches yours.

Situation	Symptom	Go to
Inbound to your infrastructure — Draftable connects to your TLS-enabled RabbitMQ or Redis	Services fail to start or cannot reach the broker or cache	TLS to RabbitMQ and Redis
Outbound to the internet — Draftable’s HTTPS traffic is intercepted by an inspecting proxy or internal CA	Licence activation fails with a certificate verification error	Outbound HTTPS and licence activation

Both are solved by installing your CA, but the outbound case needs one extra step that catches most people out, so do not stop at Step 1 if licence activation is your problem.

TLS to RabbitMQ and Redis

This section applies when your RabbitMQ broker or Redis cache presents a TLS certificate issued by a CA that is not publicly trusted. Common examples are an internal enterprise CA (such as Venafi or an internal PKI), a self-managed RabbitMQ with an internally issued certificate, or AWS ElastiCache with in-transit encryption enabled.

If your broker or cache uses a publicly trusted certificate (for example Amazon MQ’s default certificate or AWS ACM), no extra steps are needed. The steps below apply only when the certificate is issued by a private or internal CA.

Why this is required

Draftable’s services perform full TLS certificate validation on their outbound connections to RabbitMQ and Redis. They verify both:

The certificate chain — the issuing CA must be trusted by the container.
The hostname — the certificate’s Subject Alternative Name (SAN) must match the hostname the service connects to.

A privately issued certificate is valid, but the container has no reason to trust the issuer until you install your CA. If the CA is not trusted, or the SAN does not match the hostname, the connection is rejected.

TLS support for the compare service (RabbitMQ) and the converter (Redis) requires apish-compare and apish-converter version 3.0.3 or later. Ensure your images are current before configuring TLS.

Which services need the CA

Install your CA in every application container that connects to RabbitMQ or Redis over TLS:

Service	RabbitMQ (TLS)	Redis (TLS)
web	✅	✅
celery-worker	✅	✅
celery-beat	✅	✅
compare	✅	✅
converter	—	✅

The simplest approach is to install the CA in all of the application containers.

Step 1 — Trust your CA in the containers

Draftable’s containers run on Linux and use the operating system trust store. There are two supported approaches.

Option A — Add the CA to the image (recommended)

Extend the relevant Draftable images to add your CA to the OS trust store. This is persistent and applies automatically wherever the image runs:

FROM draftable/apish-web:latest
COPY your-internal-ca.crt /usr/local/share/ca-certificates/your-internal-ca.crt
RUN update-ca-certificates

Repeat for draftable/apish-compare and draftable/apish-converter. Include the full chain (root plus any intermediate CAs).

Option B — Mount the CA and point the runtime at it

If you prefer not to rebuild the images, mount your CA bundle into the pods and set the standard OpenSSL environment variables, which Draftable’s services honour on Linux:

SSL_CERT_FILE: /etc/ssl/certs/ca-bundle-including-your-ca.crt

(or SSL_CERT_DIR pointing at a directory that includes your CA). On Kubernetes this is commonly done with an init container that appends your CA to the system bundle in a shared volume.

Step 2 — Enable TLS on the connections

Set the TLS environment variables on the services. See the Docker Compose guide for the full variable reference.

# RabbitMQ over TLS
AMQP_PORT: "5671"
AMQP_TLS:  "true"

# Redis over TLS (e.g. ElastiCache with in-transit encryption)
REDIS_PORT: "6380"
REDIS_TLS:  "true"

The hostname you connect to (AMQP_HOST / REDIS_HOST) must be present in the certificate’s Subject Alternative Name (SAN). If your certificate was issued for a different name, the connection will fail certificate validation even when the CA is trusted.

Step 3 — Verify

From inside one of the application pods (or any pod in the same namespace that has openssl), confirm the certificate is trusted and the name matches:

# RabbitMQ
openssl s_client -connect <your-rabbitmq-host>:5671 -servername <your-rabbitmq-host>

# Redis
openssl s_client -connect <your-redis-host>:6380 -servername <your-redis-host>

Check two things in the output:

Verify return code: 0 (ok) — the certificate chain is trusted in that container. unable to get local issuer certificate means the CA is not trusted there (revisit Step 1).
Subject Alternative Name — confirm it lists the exact hostname you connect to.

Outbound HTTPS and licence activation

This section applies when Draftable’s own outbound HTTPS requests are intercepted and re-signed by an internal CA. This is common in enterprise networks that run TLS inspection on egress traffic, or that force all outbound traffic through an inspecting proxy.

The symptom

Licence activation fails, and the logs contain a certificate verification error:

ssl.SSLCertVerificationError: [SSL: CERTIFICATE_VERIFY_FAILED]
certificate verify failed: unable to get local issuer certificate (_ssl.c:1145)

The instance otherwise appears healthy. Comparisons may fail with errors that look like an unlicensed container, because the licence was never successfully activated.

Why it happens

API Self-Hosted contacts Draftable’s licensing service over HTTPS to activate your licence, and again periodically to revalidate it:

https://draftable.com/licensing/v2/activate
https://draftable.com/licensing/v2/validate

When your network inspects TLS, the certificate the container receives is not Draftable’s certificate. It is a substitute issued by your internal CA. The container has no reason to trust that CA, so it correctly rejects the connection.

Because the licence is also revalidated periodically, this can surface well after a successful deployment. An instance that activated on a network without inspection, then moved behind an inspecting proxy, will begin failing validation later.

The step that catches everyone out

Draftable’s licensing client is written in Python and uses the requests library. requests does not read the operating system trust store. It uses its own bundled CA list. This means that adding your CA with update-ca-certificates alone, which is sufficient for RabbitMQ and Redis, will not fix licence activation. You must also point the Python HTTP stack at a bundle that includes your CA.

Fix

Obtain your internal CA certificate

Get the full chain from your PKI or certificate team: the root CA and any intermediates, as base-64 encoded PEM files.If you do not have them to hand, you can export them from a browser. Visit https://draftable.com from a machine on the affected network, inspect the certificate, and export every certificate in the chain. On an inspected network these will be your internal CA’s certificates rather than Draftable’s public ones, which is itself confirmation that inspection is in play.

Install the CA in the trust store

Use either approach from Step 1 in the section above. Extending the image is recommended:

FROM draftable/apish-web:latest
COPY internal-root-ca.crt /usr/local/share/ca-certificates/internal-root-ca.crt
COPY internal-intermediate-ca.crt /usr/local/share/ca-certificates/internal-intermediate-ca.crt
RUN update-ca-certificates

Point the Python HTTP stack at the system bundle

This is the extra step. Set REQUESTS_CA_BUNDLE on every service that makes outbound HTTPS requests:

environment:
  REQUESTS_CA_BUNDLE: /etc/ssl/certs/ca-certificates.crt
  SSL_CERT_FILE: /etc/ssl/certs/ca-certificates.crt

/etc/ssl/certs/ca-certificates.crt is the combined bundle that update-ca-certificates writes, so it now contains both the public CAs and yours.Set these on the web, celery-worker and celery-beat services at minimum. Setting them on all application services is simplest and does no harm.

Recreate the containers and activate

Environment variables are read at start-up, so recreate the containers rather than restarting them in place. Then activate your licence again.

Verify

From inside a running container, confirm the chain is trusted:

openssl s_client -connect draftable.com:443 -servername draftable.com </dev/null 2>&1 | grep -E "Verify return code|issuer"

A Verify return code: 0 (ok) means the trust store is correct. Then confirm the Python stack agrees, which is the check that actually matters here:

python -c "import requests; print(requests.get('https://draftable.com/licensing/v2/validate').status_code)"

Any HTTP status code means TLS succeeded. An SSLCertVerificationError means REQUESTS_CA_BUNDLE is not set or is not pointing at a bundle containing your CA.

Other outbound HTTPS

The same fix applies to any other outbound HTTPS request your instance makes. The most common is fetching documents supplied as a source_url when that URL is served by an internal web server using an internally issued certificate.

An alternative to intercepting Draftable’s traffic is to exempt Draftable’s licensing endpoints from TLS inspection at the proxy. If your security team is willing to allowlist draftable.com, no CA installation is needed for licence activation. See the network requirements article for the full list of endpoints.

Troubleshooting

Licence activation fails with 'unable to get local issuer certificate' even though I installed the CA

This is almost always the missing REQUESTS_CA_BUNDLE variable. Installing the CA in the OS trust store is not enough for licence activation, because the Python HTTP client does not read the OS trust store. See Outbound HTTPS and licence activation.Also confirm you recreated the containers rather than restarting them, since environment variables are only read at start-up.

Activation worked, then started failing weeks later

The licence is revalidated periodically against Draftable’s licensing service. If TLS inspection was introduced on your network after the instance was first activated, revalidation will begin to fail while everything else appears normal. Apply the outbound HTTPS fix above.

A service cannot connect, but openssl from the pod succeeds

Confirm the CA is installed in that specific service’s container, not only in some of them. Each container has its own trust store, so the CA must be present in every service that connects over TLS (see the table above).

unable to get local issuer certificate

The CA chain is not trusted inside the container. Make sure you included the full chain (root plus intermediates) and that update-ca-certificates ran (Option A), or that SSL_CERT_FILE / SSL_CERT_DIR points at a bundle that includes your CA (Option B).

Certificate name mismatch

The hostname in AMQP_HOST / REDIS_HOST is not in the certificate’s SAN. Reissue the certificate with a SAN that includes the exact hostname your services use to connect.

Getting Started

Configuration

Deployment Guides

Migration

Instance Management

API Reference

API Self-Hosted v3 – Using a private or internal CA

TLS to RabbitMQ and Redis

Why this is required

Which services need the CA

Step 1 — Trust your CA in the containers

Step 2 — Enable TLS on the connections

Step 3 — Verify

Outbound HTTPS and licence activation

The symptom

Why it happens

The step that catches everyone out

Fix

Verify

Other outbound HTTPS

Troubleshooting

​TLS to RabbitMQ and Redis

​Why this is required

​Which services need the CA

​Step 1 — Trust your CA in the containers

​Step 2 — Enable TLS on the connections

​Step 3 — Verify

​Outbound HTTPS and licence activation

​The symptom

​Why it happens

​The step that catches everyone out

​Fix

​Verify

​Other outbound HTTPS

​Troubleshooting

TLS to RabbitMQ and Redis

Why this is required

Which services need the CA

Step 1 — Trust your CA in the containers

Step 2 — Enable TLS on the connections

Step 3 — Verify

Outbound HTTPS and licence activation

The symptom

Why it happens

The step that catches everyone out

Fix

Verify

Other outbound HTTPS

Troubleshooting