How to Run DeepWiki with Self-Signed Certificates in Production

To run DeepWiki with self-signed certificates in production, place your .crt or .pem files in a directory and build the Docker image using the CUSTOM_CERT_DIR build argument, which triggers update-ca-certificates to embed your CA trust into the container image.

DeepWiki from AsyncFuncAI/deepwiki-open packages a Next.js frontend and Python FastAPI backend into a unified Docker image for production deployments. When operating behind corporate TLS termination or private PKI infrastructure, running DeepWiki with self-signed certificates in production requires build-time certificate injection to ensure the container's OpenSSL library trusts your internal Certificate Authorities before the API server starts.

Prerequisites for Production Deployment

Before configuring DeepWiki for self-signed certificate environments, ensure you have:

• Docker Engine 20.10 or later with buildx support
• Self-signed CA certificates in PEM or CRT format
• Access to the AsyncFuncAI/deepwiki-open repository

The certificate files must be available on the build host before executing the Docker build command.

Step-by-Step Build Procedure

DeepWiki implements certificate trust through a Docker build argument that copies custom CAs into the image and updates the system trust store.

Step 1: Prepare the Certificate Directory

Create a directory in the project root to store your certificate files:

mkdir -p certs
cp /path/to/your-ca.crt certs/
cp /path/to/your-intermediate.pem certs/

The default build configuration expects this directory to be named certs/ at the repository root.

Step 2: Build with Custom Certificates

Execute the Docker build command with the CUSTOM_CERT_DIR argument:

docker build -t deepwiki-open .

If you used a different directory name, specify it explicitly:

docker build --build-arg CUSTOM_CERT_DIR=my-custom-certs -t deepwiki-open .

During the build process, the Dockerfile (lines 56-66) copies the specified directory to /usr/local/share/ca-certificates/ and executes update-ca-certificates to regenerate the CA bundle that OpenSSL uses.

Step 3: Run the Production Container

Start the container with your environment variables:

docker run -d \
  -p 8001:8001 \
  -p 3000:3000 \
  -e OPENAI_API_KEY=$OPENAI_API_KEY \
  -e GOOGLE_API_KEY=$GOOGLE_API_KEY \
  deepwiki-open

The container launches the FastAPI backend (api/main.py) and Next.js frontend through the generated start.sh script (defined in Dockerfile lines 82-100), which loads environment variables and manages both processes.

Step 4: Verify Certificate Trust

Confirm that the container trusts your self-signed CA:

docker exec -it $(docker ps -q -f ancestor=deepwiki-open) \
  openssl s_client -connect your-internal-api.com:443 -CApath /usr/local/share/ca-certificates

A successful handshake without "certificate verify failed" errors confirms proper configuration.

How Certificate Injection Works

The DeepWiki Dockerfile implements a multi-stage build that handles certificate trust at the OS level. When CUSTOM_CERT_DIR is provided, the build:

1. Copies certificate files from the build context to /usr/local/share/ca-certificates/
2. Executes update-ca-certificates to rebuild /etc/ssl/certs/ca-certificates.crt
3. Ensures the Python requests library and Node.js https module inherit this trust store

This approach bakes the certificates into the image, eliminating runtime volume mounts and ensuring the container remains portable across different production hosts.

Production Deployment Considerations

When running DeepWiki with self-signed certificates in production environments, consider these operational factors:

• Image immutability: Because certificates are embedded at build time, rotating a CA requires rebuilding the image and redeploying the container
• Secret management: Avoid committing certificate files to version control; use secure build contexts or Docker BuildKit secrets for sensitive CAs
• Multi-environment builds: Create separate image tags for environments with different certificate authorities (e.g., deepwiki:prod-corporate vs deepwiki:prod-public)

Summary

• DeepWiki bundles a Next.js frontend and Python backend into a single Docker image that requires certificate trust configuration for self-signed CA environments
• The Dockerfile accepts a CUSTOM_CERT_DIR build argument to inject certificates at lines 56-66, running update-ca-certificates to update the system trust store
• Place .crt or .pem files in a certs/ directory, build with docker build -t deepwiki-open ., and run with standard port mappings
• The container executes api/main.py and the frontend via the generated start.sh script (Dockerfile lines 82-100), inheriting custom CA trust automatically for all TLS connections

Frequently Asked Questions

How do I update certificates without rebuilding the entire image?

You must rebuild the image to update embedded certificates because DeepWiki bakes the CA trust into the container at build time. The Dockerfile copies certificates from CUSTOM_CERT_DIR and runs update-ca-certificates during the build process, not at runtime. For environments requiring frequent certificate rotation, consider mounting a volume to /usr/local/share/ca-certificates and overriding the entrypoint to run update-ca-certificates before starting the application, though this deviates from the standard production deployment model documented in the README.

What certificate formats does DeepWiki support?

DeepWiki supports standard PEM and CRT formats compatible with Debian-based update-ca-certificates. The Dockerfile copies all files from the specified CUSTOM_CERT_DIR to /usr/local/share/ca-certificates/, and the system utility processes any valid X.509 certificates it finds there. Ensure your certificate files have .crt or .pem extensions and contain Base64-encoded certificate data, including the BEGIN CERTIFICATE and END CERTIFICATE delimiters.

Can I use environment variables instead of build arguments for certificates?

No, the standard DeepWiki implementation requires build-time injection via CUSTOM_CERT_DIR rather than runtime environment variables. The certificates must be present in the filesystem before the container starts so that OpenSSL and Python's requests library can validate TLS connections immediately upon startup. While you could theoretically mount certificates as volumes at runtime, the official production procedure documented in the README at lines 442-455 and implemented in the Dockerfile emphasizes baking the certificates into the image for portability and immutability.

How do I verify that my self-signed certificates are properly loaded?

You can verify certificate trust by executing an OpenSSL command inside the running container. Run docker exec to access the container and use openssl s_client -connect <hostname>:443 -CApath /usr/local/share/ca-certificates to test the connection. If the certificate chain validates successfully, OpenSSL will report Verify return code: 0 (ok). Additionally, the DeepWiki application logs should not show TLS verification errors when making outbound HTTPS requests to services protected by your self-signed CA, confirming that both the Python backend (api/main.py) and Node.js frontend trust your internal Certificate Authority.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}