Why ERPNext SSL certificates and custom domains need a deliberate plan
HTTPS and a custom domain are set per site in ERPNext, and how you get them depends on how you deployed it. A site that staff, customers or integrations must reach under a hostname such as erp.example.com needs a certificate that clients trust, a DNS record that points to the right server, and a proxy that routes requests to the correct site. Decide these three things before go-live, because changing the hostname later affects user links, email templates, API clients and any single sign-on redirect URLs that point at the old name.
The three paths handle certificates differently. With bench, the Linux command line tool, you can set up Let's Encrypt certificates through bench for a production install, which suits a single server you manage directly. The frappe_docker how-to guides describe two container-based options: HTTPS with nginx-proxy and the ACME companion, and HTTPS with Caddy. Teams running Docker Compose usually choose between these based on whether they already operate NGINX and want to manage certificate renewal alongside it, or prefer a proxy that handles TLS with less configuration. Confirm the exact steps for your version in the frappe_docker how-to guides before you build the proxy layer.
Your choice also determines who owns renewal. In the nginx-proxy setup, the ACME companion handles issuing and renewing certificates, so you must confirm that port 80 or the challenge method is reachable and that renewal failures are monitored. Whatever path you pick, ask your team to write down who renews certificates, where the private keys are stored, and how a custom domain is added for a second site later. Those answers belong in the plan before the first certificate is requested.
How certificates are handled in each ERPNext deployment path
On a bench-managed server, the certificate is issued on the host itself. Bench includes a Let's Encrypt setup step that requests a certificate for the site's domain and wires it into the NGINX configuration that bench generates. The operator must have DNS pointing the domain at the server and port 80 reachable so the ACME challenge can complete. Renewal is not handled by ERPNext. It depends on the scheduled renewal job configured on the host, so the team owns that job and its failure alerts.
- Issuance: the certificate is requested on the server during the production setup and tied to a specific site name.
- Renewal: handled by a host-level scheduled task that the operator verifies after installation.
- Configuration: the domain must resolve to the server before the request, and the NGINX configuration generated by bench is the file to review.
- Custom domains: added by pointing a new DNS record at the server and requesting a certificate for that name on the site.
- Reloads: NGINX must reload after each renewal, so confirm the hook is present.
After go-live, confirm the expiry date of the live certificate and run a renewal dry run on the host.
The frappe_docker how-to guides describe HTTPS with an nginx-proxy setup paired with the ACME companion. In this model, a proxy container routes traffic to the ERPNext services, and a companion container watches for the domain names declared on those services, requests certificates and writes them to a shared volume. The ERPNext containers themselves do not hold private keys. Renewal is performed by the companion container, which the operator must keep running and monitor.
- Issuance: requested by the ACME companion container when a service declares its domain.
- Renewal: automatic while the companion container runs and can reach the certificate authority.
- Configuration: environment variables on the proxy and service definitions in the Compose file set the hostnames and the contact address.
- Custom domains: added by declaring the new hostname on the relevant service and making sure DNS points to the host.
- Storage: the certificate and key volumes must persist across container rebuilds, or every restart may request new certificates.
Follow the guide for the exact variables for your version of frappe_docker, and check the volume mounts before you run the stack.
The frappe_docker how-to guides also describe HTTPS with Caddy. Caddy obtains and renews certificates itself when it is configured with a site address, so the reverse proxy and the certificate lifecycle sit in one component. The operator sets the domain in the Caddy configuration and makes sure ports 80 and 443 reach the host. Because Caddy manages certificates in its own data directory, that directory is the item to back up and protect.
- Issuance: Caddy requests the certificate when the domain is first served.
- Renewal: performed by Caddy in the background, so the operator watches its logs rather than a separate job.
- Configuration: the domain and upstream target are set in the Caddy configuration that ships with the guide.
- Custom domains: added as an additional site address in the Caddy configuration, with DNS in place first.
- Data directory: losing the Caddy data volume can force re-issuance and may hit certificate authority rate limits, so keep it on persistent storage.
Confirm the current Caddy version in your stack, then test renewal in a staging environment with the same domain pattern.
How the custom domain, DNS and certificate fit together
A browser request for a custom domain passes through three layers before it reaches an ERPNext site: DNS resolves the hostname to your server, a TLS terminating proxy (NGINX, Caddy or the proxy that ships with the Docker setup) presents a certificate for that hostname and decrypts the traffic, and the proxy forwards the request to the web process, which selects the ERPNext site by the Host header. Each layer depends on the one before it. If DNS points elsewhere, the certificate request fails. If the proxy receives a hostname it does not expect, the wrong site or an error page is served. Treat the three layers as one chain when you troubleshoot.
The site name is the key link. ERPNext resolves sites by hostname, so the site created in bench or the site configured in your Docker setup must match the public hostname exactly, including the subdomain. A site created as erp.example.com will not answer to erp-test.example.com, and a certificate issued for one name does not cover another. Decide the final hostname before you create the site, because renaming a site later is an operational change, not a DNS edit. Confirm the current site-naming and rename steps in the bench and frappe_docker documentation for your version.
Certificate issuance with Let's Encrypt usually relies on an HTTP-based validation step, in which the certificate authority connects to your server on port 80 and may also expect HTTPS on port 443 afterward. That makes DNS and firewalls part of the certificate work: the A or AAAA record must point to the server before you request the certificate, and ports 80 and 443 must reach the proxy from the public internet, including through any cloud security group or upstream firewall. Confirm the exact ports, validation method and renewal behavior against the current bench and frappe_docker how-to guides, because the supported options differ between the bench and Docker paths.
Which TLS option fits which ERPNext setup
This table compares four ways to serve ERPNext over HTTPS: bench with Let's Encrypt, frappe_docker with nginx-proxy and the ACME companion, frappe_docker with Caddy, and a certificate managed outside ERPNext. Read each row for the setup it suits, who renews the certificate, and the main trade-off before you choose.
| Option | Best fit | Renewal responsibility | Main trade-off |
|---|---|---|---|
| Bench with Let's Encrypt on Linux | Single bare-metal or VM install managed with bench in production mode | Your team confirms the scheduled renewal job runs and that NGINX reloads after each renewal | Certificate handling sits in the host you already maintain, so every host change must keep it working |
| frappe_docker with nginx-proxy and ACME companion | Compose-based deployment where you want automatic certificates per domain | The ACME companion requests and renews certificates; you monitor logs and DNS and port 80 reachability | More containers to understand, and the proxy must see the correct domain labels |
| frappe_docker with Caddy | Compose-based deployment where you want the proxy to manage TLS with minimal configuration | Caddy obtains and renews certificates automatically; you confirm the domain and storage volume persist | Caddy configuration differs from NGINX, so your team needs to learn it and keep custom rules aligned with the frappe_docker setup |
| External load balancer or existing reverse proxy | Organizations that already terminate TLS centrally with an approved certificate process | Your certificate team or cloud platform owns issuance and renewal; ERPNext serves plain HTTP behind the proxy | ERPNext must trust forwarded headers and the proxy must pass the correct host and protocol, or redirects and cookies break |
| Custom or commercial certificate | Domains that need an internal CA or an organization-issued certificate | Your PKI team issues, installs and rotates the certificate, including on every node that serves the site | Manual steps are easy to miss at expiry, so track certificate dates and automate installation where possible |
| Subdomain per site on a shared server | Several ERPNext sites on one host, each with its own name | Each site's certificate needs its own renewal path, whichever option you pick | Every added domain adds DNS records and certificate work; confirm the proxy covers all names |
| Air-gapped or internal-only network | Systems with no public DNS or outbound access to a certificate authority | Your internal CA issues and renews certificates, and clients must trust that CA | Automatic renewal from a public authority is not available, so expiry monitoring becomes a manual control |
Setting up HTTPS and a custom domain on ERPNext
This sequence takes an ERPNext site from a bare IP or default hostname to a custom domain served over HTTPS with a valid certificate, HTTP redirected to HTTPS, and a login that keeps working through the secure connection.
Confirm the public hostname and DNS record
Decide the public hostname that users will type, such as erp.example.com, and confirm with the DNS team that an A record (or CNAME) points to the public address of the ERPNext proxy. Check that the record resolves from outside your network using a public resolver, not only from inside your own DNS. Also confirm that inbound ports 80 and 443 reach the server, because the certificate authority and your users both need them. The step is done when the hostname resolves to the expected address from two or more external vantage points.
Set the site name and custom domain
On the bench, the site directory name is the hostname the Frappe framework uses to route requests, so the site must be created or renamed to match the public name. Add the custom domain to the site configuration and confirm the default site is the one that should answer requests for that hostname. If you run several sites on one bench, check that each hostname maps to exactly one site. The step is done when requests to the hostname reach the correct site and the site responds over plain HTTP before any certificate is added.
Choose the TLS path for your setup
Select how certificates will be issued and terminated. On a bench-based production install, Let's Encrypt is typically requested through bench and NGINX. In a Docker setup, frappe_docker's how-to guides describe HTTPS with nginx-proxy and the ACME companion, and HTTPS with Caddy. Confirm which proxy already fronts ERPNext in your environment, because only one component should terminate TLS and hold the certificate. Record the decision, the proxy owner and where certificate files or ACME storage will live. The step is done when the team has one written TLS path that matches the deployed proxy.
Issue the certificate for the hostname
Request the certificate for the exact public hostname using the chosen path, and confirm the challenge method (HTTP-01 needs port 80 reachable from the internet, DNS-based challenges need DNS API access). Keep the certificate private key on the proxy only and restrict file permissions. Confirm the certificate subject and subject alternative names match the hostname, and note the expiry date. If a company firewall or inspection proxy sits in front of the server, confirm with your security team how the challenge will pass. The step is done when the certificate file is present, names the correct hostname and is not yet near expiry.
Enable the HTTP to HTTPS redirect
Configure the proxy so that requests on port 80 for the ERPNext hostname return a permanent redirect to the HTTPS address, and serve ERPNext only over port 443 with the certificate attached. Make sure the redirect keeps the original path so deep links still work, and that the Frappe site configuration does not hard-code an http:// base URL. Reload the proxy configuration after validating its syntax. The step is done when a request to the http:// address returns a redirect to the https:// address and not a page.
Verify the chain and HTTPS from outside
Test the public endpoint from a machine outside your network using an external TLS checker or openssl from a separate host. Confirm that the served chain is complete, that the certificate matches the hostname, that the protocol versions and ciphers offered are those your security baseline allows, and that no mixed-content warnings appear when the ERPNext desk loads. Open the site in a current browser and confirm the padlock shows a trusted connection without warnings. The step is done when an external check reports a valid, complete chain and the browser shows no certificate errors.
Test login and secure cookie behavior
Sign in to ERPNext through the custom domain over HTTPS and confirm the session persists across page loads, reports and form saves. Check in the browser developer tools that the session cookies are set with the Secure attribute and that they are sent only to the custom domain. Confirm that logout clears the session and that a login attempt over plain HTTP is redirected rather than accepted. If login works on the old hostname but fails on the new one, review the site configuration and proxy headers before retesting. The step is done when a full login, navigation and logout cycle succeeds on the custom domain with secure cookies in place.
Document renewal and monitor expiry
Record how the certificate renews, including the scheduled job or ACME companion behavior, the owner who receives failure alerts, and the procedure for a manual renewal. Test the renewal path in a non-production environment or with a dry-run option where the tool supports it, and confirm the proxy reloads automatically after renewal. Add certificate expiry monitoring to the team's existing alerting so a failed renewal is noticed before users see an error. The step is done when renewal has been exercised once and an alert on expiry is assigned to a named owner.
How certificate renewal breaks and how to prevent it
Most ERPNext certificate outages come from changes made around the certificate rather than the certificate itself: DNS, firewalls, proxy containers and hostnames. Each risk below pairs a failure mode with the control that catches it before users do.
Renewal fails silently after network changes
Let's Encrypt validates your domain over HTTP or DNS, so a firewall rule that blocks port 80, a DNS record pointing at the wrong address or a changed load balancer can stop renewal without any visible error in the ERPNext UI. The certificate keeps working until its expiry date, which is why the failure looks sudden. Control: schedule a renewal test after every network change, and alert on the certificate's remaining validity from outside the server. Confirm with your network team which path renewal uses in your setup.
Proxy does not reload the new certificate
In Docker setups, the NGINX or Caddy container holds the certificate in memory or in a mounted volume. A renewed file on disk does not change what clients receive until the proxy reloads or restarts. Check that the volume holding the certificate is mounted into the proxy container and that the proxy picks up the new file. Control: after each renewal, verify the served certificate's serial number and expiry date from outside the network, not only the file on disk.
Redirect loops after a hostname change
Moving an ERPNext site to a new hostname often leaves the old redirect rule active alongside the new one. The proxy then sends HTTP to HTTPS and HTTPS back to the old name, or two sites redirect to each other. The browser shows an error that looks like a certificate problem even when the certificate is valid. Control: test each hostname with curl and follow redirects, and remove old server blocks in the same change window as the site rename.
Mixed content from hardcoded old URLs
ERPNext stores some URLs in site configuration, print formats, email templates and integration settings. If one still uses http:// or the previous domain, browsers block those assets or flag the page as partly insecure, and users see broken links or missing images. Control: search the site database and configuration for the old hostname and the http:// scheme after every domain change, and review the site's host name setting so generated links use the new HTTPS address.
Expired certificates on internal and staging sites
Staging, test and internal ERPNext sites are often set up once and then forgotten, so their certificates lapse while production stays healthy. Staff then train users on broken sites, or integrations that call the test endpoint start failing. Control: keep an inventory of every hostname with its certificate owner and renewal method, and include non-production sites in the same expiry monitoring as production. Ask your team which sites use internal certificate authorities and who renews those.
Questions teams ask before setting up ERPNext HTTPS
Can our own team set up HTTPS for ERPNext without a partner?
Yes, if your team already runs Linux servers and DNS, and has someone comfortable with NGINX or Caddy. With bench, Let's Encrypt certificates can be requested for a site through the bench tooling, and the Docker setups in frappe_docker include how-to guides for HTTPS with nginx-proxy and the ACME companion and with Caddy. The harder part is rarely the certificate itself. It is getting DNS records, firewall rules, redirects and renewal monitoring right on the first attempt and keeping them correct after the next upgrade. Ask whether one person can own each of those tasks before deciding to build it in-house.
What makes ERPNext HTTPS work take longer or cost more?
Scope is the main driver. The effort rises with the number of sites, because each domain needs its own DNS record, certificate and redirect rules. Docker setups with an existing reverse proxy require a different configuration than a bench install where NGINX is already part of the stack. Internal DNS adds work, since public certificate authorities cannot validate names that resolve only inside your network, so you may need a private CA or DNS-based validation. A shared proxy that other applications already use adds coordination with those owners. Ask any provider to list each of these factors against your environment in the written scope.
What do we need to provide before the work starts?
Expect to provide four things: access to the DNS zone that holds your ERPNext domains, administrative access to the server or cluster that hosts ERPNext, a maintenance window for the first change, and a named owner for certificate renewal. DNS access is needed to create or verify the records that point each domain at the server. Server access covers the proxy configuration, firewall ports 80 and 443 where HTTP validation is used, and the bench or Compose files. The renewal owner matters because a certificate that renews automatically can still fail silently when a port closes or a container is rebuilt, so someone must receive and act on alerts.
How long does an ERPNext HTTPS setup take?
The duration depends on scope and on how quickly DNS changes and access approvals move inside your organization. A single public domain on a server that already serves ERPNext is typically the smallest case. Several sites, internal names, a new proxy or a move from bench to Docker each add steps and verification. No fixed figure applies to every environment, so ask for a timeline tied to a written list of domains, servers and proxies, and ask which steps depend on your internal change approvals.
What does a fixed-scope engagement with DeployOpen cover for HTTPS?
A fixed-scope engagement sets the domains, servers, proxy or bench configuration, certificate method, redirects, renewal checks and handover in writing before work begins. DeployOpen plans and implements these inside your own infrastructure and documents the result so your team can operate it. Work outside the agreed scope, such as changing the ERPNext application itself, is quoted separately. DeployOpen does not issue certificates as a certificate authority and does not provide audit attestations. Request the written scope, deliverables and timeline before you compare offers, and check whether renewal monitoring is included or offered as a retainer.
Does a managed hosting option change the HTTPS decision?
Yes. Frappe Cloud is a managed hosting option, and the ERPNext pricing page lists its hosting tiers, so certificates, domains and renewal may be handled by the platform rather than by your team. That changes who owns the work, but it also changes what you can configure. Frappe's supported versions policy ties warranty coverage to a listed version and a matching support plan, and some capabilities, such as server scripts, are restricted on public shared benches. Compare managed hosting and self-hosting against your domain, data residency and customization needs before deciding who runs HTTPS.
What engineering checks confirm the certificate and proxy are correct?
Confirm that each domain resolves to the expected address, that the certificate covers every name in use, and that HTTP redirects to HTTPS without loops. Check the certificate chain and expiry date from outside your network, not only from the server, and confirm that the ERPNext site name matches the domain it is served under. Test the proxy after a container restart and after a bench update, since configuration can be overwritten. Finally, confirm that renewal runs and that a failure produces an alert to a named person.
What changes for your team after HTTPS is live
Once HTTPS is live, the certificate stops being a one-time setup task and becomes a recurring duty with a named owner. Renewal monitoring should sit with the team that runs the NGINX or Caddy proxy, not with whoever configured bench originally. For Let's Encrypt certificates issued through bench, confirm that the renewal job runs on the host, that it has write access to the certificate paths, and that someone receives an alert when it fails. A certificate that renews silently for months is still a risk if the proxy never reloads its new files, so test a renewal in a non-production environment at least once after every change to the proxy or the host.
Certificate rotation also follows proxy changes. If the team replaces the ACME companion, moves from NGINX to Caddy, or changes the container that terminates TLS, the certificate path, the reload step and the renewal mechanism all change with it. Record which component owns the certificate for each site, and update that record whenever the proxy changes. Custom domains need the same discipline. Each new or retired domain must be reflected in the site configuration for that site, in DNS, and in every integration endpoint that calls ERPNext, such as payment gateways, bank feeds, webhook receivers and single sign-on callbacks. Confirm the list of callback URLs with the teams that own those integrations before you retire an old hostname, because a stale URL usually fails quietly.
Plan a short TLS check after every ERPNext upgrade and after every change to the base image or proxy. An upgrade can change how the application builds URLs, redirects users or handles host headers, so verify that login, password reset emails, printed links and API callbacks still use the correct HTTPS address. Your operations owner should keep a simple runbook covering who renews, who reviews expiry alerts, who approves hostname changes and who checks integrations after a release. Ask your implementation partner to document these steps as part of the handover, and confirm which of them your own team will perform after go-live.
How DeployOpen works on this
DeployOpen plans, implements, hardens, documents and supports self-hosted open-source platforms inside your own infrastructure. For ERPNext SSL certificates and custom domains, we scope the domain and certificate design first, build it in your environment, and hand over a runbook your team can operate without us.
How we scope
- Inventory every public hostname, DNS zone and ERPNext site that needs a certificate before choosing a method.
- Record whether the proxy runs under bench, a Docker Compose setup with an NGINX proxy, or Caddy in front of ERPNext.
- Agree in writing which renewal, certificate authority and TLS policy options are in scope, since engagements are fixed-scope.
How we build
- Configure custom domains, DNS records and the ERPNext site settings that match each public hostname.
- Set up certificate issuance and automatic renewal, then test renewal behavior before go-live.
- Verify HTTPS redirects, certificate chains, secure cookies and ports from outside your network.
How we hand over
- Deliver a written runbook covering issuance, renewal checks, expiry alerts and the rollback steps for each domain.
- Document the configuration files, proxy settings and environment variables used, with a clear change record.
- Walk your operations and security teams through the setup and the checks they should repeat after each change.
How we support
- Ongoing support, upgrades and continuous testing are available as a retainer after handover.
- Retainers can cover certificate renewal monitoring, proxy updates and retesting after ERPNext upgrades.
- Ask us to confirm scope for any new domain, tenant or certificate authority before we add it.
