How to get Dify serving HTTPS from its bundled Nginx
Your Docker Compose Dify is probably reachable over plain HTTP today, and the next step is to serve it over HTTPS before a regulated or internal audience uses it. The bundled Nginx container is the front door of the Compose stack: it receives browser and API traffic on the published ports and forwards requests to the web and api services. That makes it the natural place to terminate TLS when you have no load balancer or ingress in front of Dify. If your organization already has a corporate load balancer, WAF or ingress that terminates TLS, the question changes to whether Dify's Nginx should only speak HTTP internally, which is a different design covered in the reverse proxy section. This page covers the TLS path inside the bundled Nginx: where certificate files go, how the Certbot challenge option fits, protocol settings, proxy timeouts for streaming responses, and the public URL variables that must change to https.
Dify's own documentation is the reference for the file layout, the Nginx configuration templates and the variable names, so check those against the release you run before editing anything. The sequence matters: confirm the external hostname and DNS record first, decide how certificates are issued and renewed, then change the proxy and the application variables together, because a mismatch between the two produces redirect loops, mixed-content errors and broken login callbacks. Verify the result from outside your network, not only from the host. DeployOpen plans and implements this work, including the certificate process your security team will want to review, as part of a fixed-scope engagement agreed in writing before work starts.
Which certificate source fits your environment
This option suits a Dify host that a certificate authority can reach over the public internet. Let's Encrypt issues the certificate after Certbot proves control of the domain, and Certbot generates the private key on the machine where it runs. Renewal is automated by Certbot's scheduled job, so the host must stay reachable and the job must keep running. Your team owns the key file on disk, and the Let's Encrypt service owns issuance policy and rate limits.
- Who issues: Let's Encrypt, using a domain validation challenge that Certbot completes for you.
- Who renews: Certbot, on a timer it installs; confirm the renewal job runs and that a dry run succeeds after each change.
- Who stores the key: Your team, in the file system path Certbot writes, so restrict read access to the Nginx service account.
- What must be reachable: Port 80 for the HTTP-01 challenge, or DNS write access for a DNS-01 challenge, plus outbound access from the host to Let's Encrypt.
- Trade-off: Public names and public exposure of the hostname are required, which may conflict with an internal-only Dify.
Before you choose this path, confirm with your security team whether a publicly trusted certificate for an internal Dify hostname is permitted under your policy.
This option fits a Dify deployment that users reach only from the corporate network, or one that your policy requires to chain to an internal root. Your PKI team issues the certificate, often from a certificate signing request you generate on the Dify host, and it controls revocation and lifetime. Clients must trust the internal root, which is a distribution task for endpoints and any service that calls Dify. Renewal is a process your PKI team and your operators run together, not a background job unless you automate it through an enrollment protocol your CA supports.
- Who issues: Your internal CA, under its certificate policy and approval workflow.
- Who renews: Your team, by a calendar, a ticket or an automated enrollment client; confirm the expiry alert owner before go-live.
- Who stores the key: Your team, and for stricter policies a hardware or managed key store that you select and document.
- What must be reachable: Nothing from the public internet for issuance, but the CA's enrollment endpoint and any revocation endpoints must be reachable from the Dify host or your admin workstation.
- Trade-off: Clients that do not trust the internal root will show certificate errors, so distribution to browsers, API callers and plugin integrations must be planned.
Ask your PKI team which certificate profile, key length and revocation method they will apply to a Dify host, and confirm that the chain includes every intermediate Nginx needs to serve.
In this model the TLS session ends at a load balancer, reverse proxy or WAF that your infrastructure team already operates, and the bundled Nginx receives traffic from that device. The certificate and key live on the upstream device, which usually means the platform team that owns that device issues, renews and stores them. Nginx may then serve plain HTTP on the internal network, and the forwarded-header and public URL settings in Dify must agree with what the load balancer presents to users. Whether you keep TLS between the load balancer and Nginx is a separate decision with its own certificate.
- Who issues: Usually your network or platform team, through the device's certificate store or a central certificate service.
- Who renews: The owner of the load balancer, under its existing renewal process; Dify does not see the renewal.
- Who stores the key: The load balancer's key store, which may be managed by a central team with its own access controls.
- What must be reachable: Public or client ports on the load balancer, and a private route from the load balancer to Nginx on the port Nginx listens on.
- Trade-off: Traffic inside the segment may be unencrypted unless you configure a second TLS hop, and the bundled Nginx configuration needs changes to avoid redirect loops.
Confirm with the load balancer owner whether the back-end leg is encrypted, and whether the proxy headers are trusted only from that device.
Configuration options and when each fits
This table compares the HTTPS decisions for a self-hosted Dify behind the bundled Nginx: certificate placement, how the certificate is issued, TLS protocol and cipher settings, streaming timeouts and public URL variables. Read each row as a choice with a cost, and confirm variable names against the Dify environment reference for your version. The main takeaway is that the challenge method and the URL variables cause most failures, so settle both before enabling redirects.
| Decision | Option | Trade-off | When it fits |
|---|---|---|---|
| Certificate placement | Certificate and key mounted into the Nginx container and referenced in its configuration | Renewals must reach the container, so a reload step belongs in every renewal | Single host where the Compose files are the source of truth |
| Challenge method: HTTP-01 | Certbot proves control through the Nginx path on port 80 | Port 80 must be reachable from the internet and the challenge path must not be redirected away | Public hostname where your network policy allows inbound port 80 |
| Challenge method: DNS | Proof through a DNS TXT record managed with a DNS provider plugin or API | No inbound port 80 needed, but the DNS API credential must be protected and rotated | Hosts with no inbound port 80 or with internal-only names |
| Certificate source: internal CA | Certificate issued by your own certificate authority and placed manually or by your tooling | Renewal depends on your internal process, and clients must trust the internal root | Regulated networks with an existing certificate authority |
| TLS protocol settings | Restrict Nginx to current protocol versions | Older clients and some internal tools may fail, so test every client type in use | Default for most deployments, relaxed only with a documented client need |
| Cipher suite profile | Adopt a maintained profile from the Nginx project or a published Mozilla guideline | Stricter profiles break legacy clients, and the chosen profile needs a written owner | Organizations that must show a defined cipher baseline to assessors |
| Long proxy timeouts | Raise Nginx read and send timeouts on the location that serves streamed responses | Longer timeouts hold connections open and can tie up capacity under load | Chat or workflow runs that stream output for a long time |
| Public URL variables | Set the console, web, service API, app web and files URL variables to the https hostname | A mismatch breaks redirects, cookies or uploads, and every hostname change repeats the update | Every deployment served over TLS, including after a hostname change |
Setting up HTTPS on the Compose stack step by step
This sequence moves a self-hosted Dify Compose stack from plain HTTP to HTTPS on its bundled Nginx service. Each step ends with a check, so the platform team can confirm that certificates, redirects, streaming and public URLs all work before users depend on the endpoint.
Confirm DNS and port reachability
The platform engineer creates or confirms the DNS record that points your Dify hostname to the Compose host, then coordinates with the network team to confirm that ports 80 and 443 reach that host from the networks that need them. If you plan to use the Certbot HTTP challenge, port 80 must be reachable from the internet for validation. Done when name resolution returns the expected address from outside your network, and a port check from outside succeeds on both ports with no other service already bound to them on the host.
Place certificate and key files
The engineer copies the full certificate chain and the private key into the directory that the Nginx service mounts in the Compose project. Confirm the exact directory, file names and the matching environment keys against the Dify Docker Compose documentation for your target version. Restrict the key file so only the account that runs Nginx can read it. Done when the certificate's subject or subject alternative name matches the hostname, and the certificate's public key matches the private key. If you issue certificates with Certbot in a later step, this step becomes a placeholder path that Certbot replaces.
Enable the HTTPS server block and redirect
In the env file, the engineer turns on the HTTPS setting, points the certificate and key variables at the file names from the previous step, and enables the redirect from HTTP to HTTPS. Confirm each variable name in the Dify environment reference and Compose docs for your version. Before restarting anything, run the Nginx configuration test inside the running container so syntax errors surface early. Done when the test reports the configuration is syntactically valid and the rendered server block lists the certificate path and a redirect for port 80.
Set long proxy timeouts for streaming
The engineer raises the proxy read and send timeouts that apply to the API and web locations so that server-sent event streams for chat and workflow runs are not cut off while a model is still generating. Confirm the timeout variable names in the Compose documentation for your version, because the defaults in a generic Nginx setup are often too short for long model responses. Done when the Nginx configuration test passes again and the rendered configuration shows the new timeout values for the locations that serve chat and workflow traffic.
Update every public URL variable to https
The engineer changes each public URL variable in the env file so that the console, web app, service API and file URLs use the https scheme and the external hostname. Confirm the exact variable names in the environment reference for your version. A mismatch breaks login redirects, file uploads and embedded apps. Do not change SECRET_KEY during this step, because changing it after deployment logs out all users. Done when a search of the env file for the old http scheme and the hostname returns no public URL values that still use http.
Restart the stack and verify TLS
The engineer recreates the Compose services so Nginx and the API pick up the new settings, then checks that all containers report healthy. From a machine outside the Compose host, the engineer opens a TLS connection to the hostname and confirms the certificate chain, the expiry date, the negotiated protocol version and the cipher policy against the organization's TLS standard. The engineer also requests the HTTP address and confirms a redirect to HTTPS. Done when the TLS check shows a trusted chain for the hostname and the HTTP request redirects to the HTTPS address.
Run a streaming chat test
The engineer publishes a simple test app with one model node, then sends a chat message through the web interface and a streaming request through the service API. The response should appear token by token and finish without a dropped connection, including on a prompt that produces a long answer. In the browser, the engineer checks that sign-in redirects return to the HTTPS hostname and that the developer console reports no mixed-content warnings. Done when the streamed answer completes in full on both paths, and the test app and its logs show no timeout or redirect errors.
Why mismatched URL variables break sign-in and file access
Several Dify settings store the public address of the platform, and each one must carry the external hostname and the https scheme. The console and web app URLs, the service API base URL and the file URL are what browsers and API clients use to call back into Dify, and the Dify environment variable reference documents how each is used. The bundled Nginx forwards requests, but it does not rewrite the URLs that Dify generates. Before you change anything, list every public URL variable in your .env file, confirm its purpose for your release in the reference, and record its current value so you can roll back.
A partial update is the most common cause of failures after a TLS change. If the console URL moves to https but a file or API URL still starts with http, the login page loads, yet some requests go to an insecure address. Browsers restrict mixed content, and scripts or API calls over http are the usual blockers, so uploads, previews or embedded calls fail while the rest of the page appears to work. Sign-in can break for a different reason: a redirect that still points to the old scheme or host sends the user to an address that does not match the session. Open browser developer tools and look for requests to http addresses or redirects to the wrong host, then test sign-in, a file upload, a file preview and a published app's API, since each exercises a different variable.
SECRET_KEY needs separate attention because, according to the environment reference, it signs session cookies and JWTs and encrypts OAuth credentials. Changing it logs out all users, so keep the existing value during the scheme change unless you have a separate reason to rotate it. Cookie behavior is the part to verify. Confirm in the reference which cookie-related settings your release exposes, then check that the session cookie is set for the public hostname and accepted after the change. If you use OAuth sign-in, confirm that the redirect URIs registered with the identity provider also use the new https address. Plan the change for a maintenance window and tell users they may need to sign in again.
Security and operational considerations for TLS termination
TLS termination at the bundled Nginx makes it the front door for the console, the apps and the API paths. The cards below cover what the certificate and proxy layer must protect and how it is kept current after each Dify release, so the HTTPS setup stays correct over time.
Private key permissions and backups
The private key for the Dify hostname is the material that lets anyone impersonate the console and API endpoints. Keep the key readable only by the account that runs Nginx, store the directory outside the repository and out of shared file paths, and confirm who holds backup copies. Back up the key with the same access controls as the server, and record where each copy lives so a restore after a failed host does not require reissuing certificates under pressure. Restrict the key to root and the Nginx service account.
Protocol and cipher review
The TLS protocol and cipher settings in the Nginx configuration should match your organization's cryptography policy, not the defaults shipped with an image or a sample file. Ask the security team which protocol versions and cipher suites are approved, test the live endpoint with an external scanner after each change, and keep the approved list in version control so reviewers can see when it changed.
Renewal monitoring and expiry alerts
Certbot renews certificates automatically only when the scheduled job runs and the HTTP challenge still reaches the server. Monitor the certificate expiry date from outside the host, alert the operations team well before it lapses, and check that renewal hooks reload Nginx after a renewal. A renewal that succeeds on disk but never reloads the proxy leaves the old certificate in service until it expires.
HSTS and redirect behavior
Once the public URL variables point at https, decide how plain HTTP requests are handled. Redirect port 80 to HTTPS for the Dify hostname, and add an HSTS header only after you have confirmed every subdomain and client path works over TLS, because browsers cache that policy. Test redirects for the console, the web apps and API calls, since a redirect on a POST request can drop the request body.
Admin console and API path exposure
The Nginx layer routes the console, the published web apps, the service API and the file upload paths. Decide which paths are reachable from the internet, which only from the corporate network, and which should not be exposed at all, then express that in the server blocks rather than relying on application login alone. Review the routing after each upgrade, because new paths can appear with a release.
Nginx image updates with each release
The Nginx container version is tied to the Compose file for each Dify release, so an upgrade can change the proxy configuration as well as the application. Read the release notes and the upgrade guide for each target version, compare the bundled Nginx template with your customized copy, and pull the updated image as part of the same change window. Dify minor releases arrive roughly monthly, so set a fixed review cadence.
Questions teams ask before setting up HTTPS for Dify
How much effort does HTTPS for a self-hosted Dify take?
The effort depends mostly on how your edge is already built, not on Dify itself. A team that runs its own Nginx or load balancer with a known DNS zone and a certificate process will spend far less time than one that must create all three from scratch. The main drivers are whether TLS terminates at the bundled Nginx or at an existing ingress, how many public hostnames Dify needs, whether you use a public certificate authority or an internal one, and how many environments (test, staging, production) must be changed. Ask for the work to be split into edge design, configuration of the Dify URL variables, validation in a test environment, and cutover, so each part can be priced and checked separately.
Can our in-house team set up HTTPS for Dify alone?
Often yes, if the team already operates Docker Compose hosts, Nginx and certificate issuance. The parts that most often stall an internal team are not the Nginx directives but the surrounding decisions: who owns the DNS record, whether the host can complete the certificate challenge from outside, and how the change fits into existing firewall and change-control rules. Check three things before you decide: whether someone can run the change and rollback in a maintenance window, whether they can verify streaming chat responses after the proxy timeouts are raised, and whether they know every place a public URL variable is used, including the plugin and file paths.
What do we need to provide before the work starts?
Plan to provide access and decisions rather than hardware. The usual inputs are:
- A DNS zone you control, with permission to create the public hostname for Dify
- Inbound rules that allow the certificate authority to reach the port it uses for validation, or a DNS method if the challenge type requires it
- Access to the Dify host, its
.envfile and the Docker Compose project directory - An agreed certificate authority and key storage location, plus a named owner for renewal alerts
- A change window for the cutover, with a tested rollback to plain HTTP settings
Confirm the exact challenge method and firewall needs with your certificate authority and network team, because they depend on your environment.
How long do validation and cutover take in our environment?
The duration is set by approvals and the validation path, not by the configuration itself. Certificate issuance can be quick once DNS and inbound access are correct, but waiting on a DNS change, a firewall ticket or a security review can take longer than the Nginx work. Cutover time depends on whether you can update the public URL variables and restart the stack in one window, and on how many clients, embedded web apps or API consumers must switch to the https address at the same time. Ask for a timeline that lists each external dependency and who owns it, so the schedule follows the real blockers.
How are certificate renewals handled after go-live?
Renewal is an ongoing operational task and should have a named owner from the first day. Certbot can renew automatically when it is scheduled correctly, but the renewal also has to reload Nginx and succeed through the same network path used at issuance. Recurring work includes monitoring expiry, confirming the renewal job runs, checking that the reload works and keeping the TLS protocol settings current with your policy. Ask whether renewal monitoring is part of your own operations, a retainer or a handover, and what evidence you will receive that the last renewal succeeded.
Does a fixed-scope engagement include testing of the HTTPS setup?
Testing is included only when it is written into the agreed scope. A typical scope for this work covers configuration review, checks that the certificate chain is served correctly, verification that every public URL variable uses https, and a test of long streaming responses through the proxy. Ask whether the scope includes a security scan of the TLS endpoint, a check of which protocol versions and cipher settings are accepted, and a rollback test. Anything beyond that, such as penetration testing of the application itself, should be scoped as a separate item so the quote stays clear.
Which parts of the HTTPS work create the most risk?
The highest-risk items are changes that look small. Changing SECRET_KEY is not part of this work, but a mismatched public URL variable can break login, OAuth callbacks or file links. Short proxy timeouts can cut off streaming responses that users see as random failures. A certificate that is valid in the browser but missing an intermediate certificate can fail in API clients and automated jobs. Ask for a checklist that covers each URL variable, a test of a long streaming request, and a test from an API client that does not use a browser.
Where to read the official Dify deployment guidance
Start with the Docker Compose quick start before you change anything in the bundled Nginx configuration. The page covers the stack the HTTPS setup modifies, including the Nginx container, the published ports and the .env file where the public URL variables live. Read it against the version you plan to deploy, because the file layout and service names are what your certificate paths and proxy settings must match. Ask your own team to confirm which copy of the Compose files and .env.example they have checked out, since a mismatch there is a common source of confusion during TLS work.
Next, read the Dify environment variable reference with a list of every URL variable in hand. The reference is where you confirm the exact variables that carry the public hostname and scheme, so that console links, API endpoints and file URLs all resolve to https. Treat it as the checklist for the URL update step. Verify each variable after the change by testing a file upload and an API call from outside the network, not only by reading the config.
Use the Dify deployment overview to confirm which deployment model your HTTPS design targets, and then check the Dify releases on GitHub before every upgrade. Release notes and the linked upgrade guides are where changes to the Nginx template, proxy behavior or environment variables are announced. Minor releases have arrived roughly monthly, so a certificate and proxy configuration you tested once will need a check on each update. Record the version you tested against so that a later upgrade can be compared with a known-good TLS setup.
How DeployOpen scopes and delivers Dify HTTPS work
DeployOpen plans, implements, hardens, documents and supports self-hosted open-source platforms inside your own infrastructure. For Dify HTTPS, that means agreeing in writing which hostnames, certificate method and proxy settings are in scope, then delivering a configured and tested TLS setup that your team can operate after handover.
How we scope
- Engagements are fixed-scope, with the TLS deliverables and timelines agreed in writing before work starts.
- The written scope lists every public hostname, the chosen Certbot challenge method and where certificates are placed.
- We confirm the external URL variables that must change to https and which clients call the Dify API directly.
- Ongoing support, upgrades and testing are available as a retainer after the initial work is handed over.
How we build
- We configure the bundled Nginx service with certificate paths, redirects from HTTP and TLS protocol settings you approve.
- Long proxy timeouts are set for streaming responses, then checked against a workflow that streams output.
- We update the public URL variables in the environment file to match the https hostname and restart the affected services.
- Certificate renewal is configured and tested so that a renewal run does not interrupt the running stack.
How we hand over
- You receive a written record of the Nginx configuration, environment changes and certificate locations.
- A runbook covers renewal checks, what to do when a challenge fails and how to roll back a config change.
- Verification notes show the browser, API and streaming checks that passed, so your team can repeat them.
- Your engineers are shown how to apply future Dify upgrades, including checking .env.example for new variables.
How we support
- Support can cover renewal monitoring, certificate changes after a hostname move and reviews after each Dify release.
- Changes to proxy settings are tested in a staging copy before they reach production, where your environment allows it.
- Security testing of the exposed endpoints is available as a separate scope when your policy requires it.
- Ask any partner, including DeployOpen, to confirm exactly which steps your team retains after handover.
