Network, DNS, and Firewall
DeskDox should be exposed through a controlled public endpoint while database, conversion, worker, and internal application service ports remain private.
Public Endpoint Model
Production users should access DeskDox through a customer-approved FQDN, for example https://deskdox.customer.example. The FQDN must align with application URL configuration because outbound email links, public document links, password reset links, and integration callbacks depend on the configured public URL.
The recommended enterprise pattern is:
- Customer DNS resolves the FQDN to the approved reverse proxy, load balancer, gateway, or host.
- TLS terminates at the customer-approved edge or reverse proxy.
- The reverse proxy forwards user traffic to the DeskDox frontend service.
- The frontend NGINX proxy forwards
/api/calls to the backend over the internal Docker network.
DNS Requirement
DNS must be confirmed before production validation. If the final FQDN is not available during installation, a temporary URL may be used only for implementation testing and must be replaced before go-live. Production must not retain local-only or temporary implementation hostnames in FRONTEND_URL, PUBLIC_URL, or allowed-origin settings.
TLS Certificate Requirement
Production access should use HTTPS. The certificate may be managed by the customer reverse proxy, gateway, cloud load balancer, or another approved TLS termination point. Certificate issuance, renewal, private key custody, and HSTS policy are customer-controlled unless explicitly included in the implementation scope.
Exposure Rules
- PostgreSQL must remain internal-only.
- Gotenberg/converter must remain internal-only.
- Worker services must not expose public ports.
- Backend direct exposure should be avoided unless explicitly required by the deployment model and approved by architecture/security review.
- The public surface should be limited to HTTPS for the DeskDox web endpoint and only optional webhook endpoints required by enabled integrations.
Production Network Flow
flowchart LR
Browser["Browser"] -->|HTTPS 443| Edge["Customer reverse proxy or TLS edge"]
Edge --> Frontend["frontend"]
Frontend -->|same-origin API proxy| Backend["backend"]
Backend -->|internal only| Postgres[("postgres 5432")]
Backend -->|internal only| Gotenberg["gotenberg 3000"]
Backend --> Files[("document storage")]
Preview["preview-worker"] --> Files
Preview --> Gotenberg
Index["index-worker"] --> Files
Backend -->|outbound when enabled| SMTP["SMTP relay"]
Backend -->|outbound when enabled| AI["AI endpoint"]
Backend -->|outbound when enabled| WhatsApp["WhatsApp Cloud API"]Inbound User-Facing Ports
| Port | Protocol | Destination | Purpose | Exposure guidance |
|---|---|---|---|---|
443 | HTTPS | Customer reverse proxy, gateway, or DeskDox endpoint | Primary production web access | Normal production access path. |
80 | HTTP | Customer edge or DeskDox frontend | Redirect to HTTPS or certificate validation | Optional; restrict or redirect according to customer policy. |
8080 | HTTP | frontend in root production Compose | Frontend HTTP binding | Bound to the loopback interface in docker-compose.prod.yml; use behind a reverse proxy. |
8088 | HTTP | frontend in Windows deploy-kit Compose | Default Windows install frontend port | Configurable through HTTP_PORT; review HOST_BIND_IP and host firewall before production use. |
Internal-Only Service Ports
| Port | Service | Used by | Exposure guidance |
|---|---|---|---|
8000 | backend API | frontend NGINX proxy and internal services | Internal only. Avoid direct public exposure unless a reviewed deployment model requires it. |
5432 | postgres | backend, workers, backup/restore processes | Internal only. Never expose PostgreSQL to the internet. |
3000 | gotenberg | backend and preview-worker | Internal only. Root production Compose binds it to loopback for host diagnostics. |
| N/A | preview-worker, index-worker | Internal job processing | No public ports. Workers communicate through database and mounted storage. |
Outbound Integration Ports
| Port | Destination | Purpose | Required when |
|---|---|---|---|
587 | SMTP relay | Email notifications and document email | Email is enabled and relay uses SMTP submission. |
465 | SMTP relay | Alternative SMTPS transport | The customer relay requires SMTPS. |
25 | SMTP relay | Customer-specific SMTP relay | The customer relay uses port 25. |
443 | WhatsApp Cloud API | WhatsApp integration | WhatsApp integration is enabled. |
443 | OpenAI, Azure OpenAI, or compatible AI endpoint | Emii, LLM, or embedding features | Cloud AI or external AI is enabled. |
11434 | Ollama endpoint | Local LLM integration | Ollama is enabled outside the container network. |
SMTP, WhatsApp, OpenAI/Azure/OpenAI-compatible endpoints, and local/customer-hosted LLM endpoints are outbound dependencies only. The customer must approve outbound firewall rules, proxy settings, TLS inspection behavior, rate limits, and credential custody.
If Emii or cloud AI is disabled, outbound OpenAI/Azure access is not required. If WhatsApp is disabled, Meta WhatsApp Cloud API access is not required.
Internal-Only Services
The following services must not be reachable from the internet:
postgresgotenbergpreview-workerindex-worker- direct backend port
8000, except through a reviewed and approved reverse proxy pattern - Docker daemon or Docker socket
Network Readiness Checks
Before go-live:
- The production FQDN resolves correctly.
- HTTPS certificate is valid and trusted by customer browsers.
- Application links use the production FQDN.
- Public users cannot reach PostgreSQL, Gotenberg, workers, or Docker services.
- SMTP and enabled external integrations are tested from the deployed environment.
- Firewall decisions and the network owner are recorded in deployment handover notes.