Allow for customized self signed cert by porthorian · Pull Request #173 · linuxserver/docker-unifi-network-application

porthorian · 2026-02-08T16:24:09Z

Before submitting a pull request please check the following

If this is a fix for a typo (in code, documentation, or the README) please file an issue and let us sort it out. We do not need a PR
- This is not a fix for a typo.
Ask yourself if this modification is something the whole userbase will benefit from, if this is a specific change for corner case functionality or plugins please look at making a Docker Mod or local script https://blog.linuxserver.io/2019/09/14/customizing-our-containers/
- I think this modification is something the whole userbase could benefit from, giving more flexibility inside the container itself without having to copy pasta the entire init script for a docker mod to work.
That if the PR is addressing an existing issue include, closes # , in the body of the PR commit message
- It does not address an existing issue, but it does come out of the want to specify a self signed certificate so a reverse proxy can use that to encrypt the traffic between the two applications.
I have read the contributing guideline and understand that I have made the correct modifications

Description:

On the first initialization of the unifi network application via this application, it checks to see if there is a mounted keystore.jks file if there is, the script will proceed to importing that jks into the keystore. Rather then auto generating a unique key that is pretty hard to modify once the container is created if using kubernetes, or a different certificate that wasn't generated.

Benefits of this PR and context:

The benefits of this PR are in my opinion allow for no hack arounds to occur to get this to work with a reverse proxy that isn't traefik and encrypt the traffic via tls from the proxy to the controller.
This allows users to bring their own certificates as long as they are signed appropriately and will work with unifi.
An example of this is cert-manager.

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: self-signed-svc-cert
spec:
  dnsNames:
    - {your-domain-name}
  secretName: unifi-signed-cert
  commonName: unifi
  issuerRef:
    name: self-signed-ca-issuer
    kind: ClusterIssuer
    group: cert-manager.io
  keystores:
    jks:
      alias: unifi
      create: true
      # This is really just aircontrolenterprise as it has to be.
      passwordSecretRef:
        name: unifi-keystore
        key: password

This allows the user to create a self signed certificate that allows them to use this on a reverse proxy application for example. NGINX that is using the gatewapi implementation BackendTLSPolicy.

This is largely because there is no way at all to turn off insecure ski verfication for some ingress implementations.
https://docs.linuxserver.io/images/docker-unifi-network-application/#strict-reverse-proxies

This solves this problem altogether.
https://docs.linuxserver.io/images/docker-unifi-network-application/#strict-reverse-proxies

Users can now bring their own certificate and not have to worry about configuring it after the fact.

How Has This Been Tested?

Manual validation in Kubernetes with cert-manager:

Deployed cert-manager and created a Certificate resource (example above) with secretName: unifi-signed-cert and JKS keystore output enabled.
Verified the unifi-signed-cert secret was created by cert-manager.
Mounted that secret into the UniFi container as a volume:

In Kubernetes looks like this

pod:
  spec:
    containers:
      volumeMounts:
        - name: certs-vol
          mountPath: /certs
          readOnly: true
    volumes:
    - name: certs-vol
      secret:
        secretName: unifi-signed-cert

Redeployed the workload and confirmed UniFi started successfully using the mounted keystore/certificate instead of requiring post-start certificate replacement.
Verified reverse-proxy-to-UniFi TLS works with the provided certificate.

Post Change

I have been running this in my homelab now with a pretty complicated unifi setup and have had no issues since, running behind a nginx proxy.

Updates to Documentation

In order for a user to import at the start of a initial container, they need to mount the certificate on the container too /certs/keystore.jks.

Source / References:

[FEAT] Add docs for custom SSL certificate #78
adding support for secrets for backendtlspolicy nginx/nginx-gateway-fabric#3084 (also the reason why I had to go through this amount of effort)

github-actions

Thanks for opening this pull request! Be sure to follow the pull request template!

LinuxServer-CI · 2026-02-08T16:29:28Z