HTTP and HTTPS settings

Mango includes an embedded Jetty web server that serves the browser-based UI, the REST API, and WebSocket connections. The HTTP and HTTPS settings in mango.properties control how this server listens for connections, manages threads, handles file uploads, and interacts with reverse proxies.

Understanding these settings is important when deploying Mango in production, especially when running behind a load balancer or reverse proxy such as Nginx or Apache.

Overview

All HTTP-related settings are configured in the mango.properties file located in your mango-data/ directory. Changes to these settings require a Mango restart to take effect. The settings fall into several categories:

• Port configuration -- which ports the server listens on
• SSL/TLS -- enabling HTTPS and configuring certificates
• Thread pool -- how many concurrent requests the server can handle
• WebSocket -- real-time communication settings
• Reverse proxy -- forwarded header handling
• Upload limits -- maximum file upload sizes
• CORS -- cross-origin resource sharing for external API clients
• Default servlet -- static file serving behavior

Port configuration

Mango listens on HTTP and optionally HTTPS ports. By default, only HTTP is enabled.

Parameter	Type	Default	Description
web.port	Integer	8080	HTTP listening port. Set to -1 to disable HTTP entirely (useful when SSL is the only allowed transport).
ssl.port	Integer	8443	HTTPS listening port. Only active when ssl.on=true.
ssl.on	Boolean	false	Enables the HTTPS connector. Requires a valid keystore configured in the SSL settings.

Choosing ports

• Development: The defaults (8080 / 8443) work well for local development and testing.
• Production without reverse proxy: Set web.port=80 and ssl.port=443 so users do not need to specify a port in the URL. On Linux, this requires running Mango as root or using setcap to grant the CAP_NET_BIND_SERVICE capability to the Java binary.
• Production with reverse proxy: Keep the default high ports and let the reverse proxy (Nginx, Apache, HAProxy) handle ports 80/443. This is the recommended production architecture.

When SSL is enabled, you can optionally redirect all HTTP traffic to HTTPS by setting ssl.on=true and configuring your reverse proxy to redirect port 80 to 443.

Thread pool configuration

The embedded Jetty server uses a thread pool to handle incoming requests. Each active HTTP request, REST API call, or WebSocket connection consumes one thread from this pool.

Parameter	Type	Default	Description
web.threads.minimum	Integer	10	Minimum number of threads kept alive in the pool, even when idle.
web.threads.maximum	Integer	200	Maximum number of threads the pool can grow to under load.

Sizing guidelines

• Small deployment (< 10 concurrent users): The defaults are sufficient.
• Medium deployment (10-50 concurrent users): Consider increasing web.threads.maximum to 300.
• Large deployment (50+ concurrent users or heavy API usage): Set web.threads.maximum to 400 or higher. Monitor thread utilization to fine-tune.

Each thread consumes memory (typically 512KB-1MB of stack space). Setting web.threads.maximum to an extremely high value (e.g., 2000) without sufficient heap memory will cause OutOfMemoryError. As a rule of thumb, ensure your JVM heap can support the maximum thread count.

WebSocket settings

Mango uses WebSocket connections for real-time updates in the browser UI, including live point values, event notifications, and terminal sessions.

Parameter	Type	Default	Description
web.websocket.maxIdleTimeout	Integer (ms)	60000	How long a WebSocket connection can remain idle before the server closes it. Set to 0 for no timeout.
web.websocket.maxTextMessageSize	Integer (bytes)	65536	Maximum size of a single WebSocket text message.
web.websocket.maxBinaryMessageSize	Integer (bytes)	65536	Maximum size of a single WebSocket binary message.
web.websocket.inputBufferSize	Integer (bytes)	8192	Input buffer size per connection.

Most deployments do not need to change WebSocket settings. If you see frequent disconnections in the browser, increase web.websocket.maxIdleTimeout to 120000 (2 minutes). If you are behind a reverse proxy, ensure the proxy also supports WebSocket passthrough (see the reverse proxy section below).

Forwarded headers (reverse proxy)

When Mango runs behind a reverse proxy, the proxy terminates the client connection and forwards the request to Mango. Without forwarded header support, Mango sees all requests as coming from the proxy's IP address, and it cannot determine whether the original request used HTTPS.

Parameter	Type	Default	Description
web.forwardedHeaders.enabled	Boolean	false	Enables processing of X-Forwarded-For, X-Forwarded-Proto, X-Forwarded-Host, and X-Forwarded-Port headers.

When to enable: Enable this setting whenever Mango is behind a reverse proxy (Nginx, Apache, HAProxy, AWS ALB, etc.). This ensures:

• Correct client IP logging -- audit logs show the real client IP instead of the proxy IP.
• Correct protocol detection -- Mango knows the original request used HTTPS even though the proxy-to-Mango connection may be HTTP.
• Correct redirect URLs -- login redirects and API responses include the correct scheme and host.

Security warning: Do not enable web.forwardedHeaders.enabled if Mango is directly exposed to the internet without a proxy. An attacker could forge these headers to spoof their IP address or force incorrect protocol detection.

Example Nginx configuration

server {
    listen 443 ssl;
    server_name mango.example.com;

    location / {
        proxy_pass http://localhost:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # WebSocket support
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

Upload limits

Mango limits the size of HTTP request bodies to prevent accidental or malicious upload of excessively large files.

Parameter	Type	Default	Description
web.multipart.maxFileSize	String	500MB	Maximum size of a single uploaded file. Accepts values like 10MB, 1GB.
web.multipart.maxRequestSize	String	500MB	Maximum total size of a multipart request (all files combined).

If users need to upload large backup files or bulk import files, increase these values accordingly. Keep in mind that very large uploads will consume proportional heap memory during processing.

CORS configuration

Cross-Origin Resource Sharing (CORS) controls which external web applications can access the Mango REST API from a browser. By default, CORS is disabled, meaning only pages served by Mango itself can call the API.

Parameter	Type	Default	Description
rest.cors.enabled	Boolean	false	Enables CORS headers on REST API responses.
rest.cors.allowedOrigins	String	""	Comma-separated list of allowed origins (e.g., https://dashboard.example.com). Use * to allow all origins (not recommended for production).
rest.cors.allowedMethods	String	GET,POST,PUT,DELETE,OPTIONS	HTTP methods that external origins are permitted to use.
rest.cors.allowedHeaders	String	content-type,authorization	HTTP headers that external origins are permitted to send.
rest.cors.allowCredentials	Boolean	true	Whether browsers should send cookies and authorization headers with cross-origin requests.

When to enable: Enable CORS when you have a separate front-end application (e.g., a custom React dashboard) hosted on a different domain that needs to call the Mango REST API directly from the browser.

When NOT to enable: If your front-end is served by Mango itself, or if API calls originate from a backend server (Node.js, Python), CORS is not needed.

Default servlet settings

The default servlet handles requests for static files (HTML, CSS, JavaScript, images) that are not matched by the REST API or other servlets.

Parameter	Type	Default	Description
web.defaultServlet.cacheControl.maxAge	Integer (seconds)	0	Browser cache duration for static assets. Set to 86400 (1 day) or higher in production to reduce bandwidth.
web.defaultServlet.etags	Boolean	true	Enables ETag-based conditional caching. Browsers can use If-None-Match to avoid re-downloading unchanged files.

For production deployments, setting a non-zero maxAge reduces server load and improves page load times. Use cache-busting filenames (e.g., app.abc123.js) if you need to ensure users get updated files immediately after an upgrade.

Troubleshooting

Symptom	Likely cause	Solution
"Address already in use" on startup	Another process is using the configured port	Check for conflicting processes with `netstat -tlnp
"Connection refused" when accessing Mango	Mango is not running, wrong port, or firewall blocking	Verify Mango is running, check web.port matches the URL, and ensure the firewall allows inbound traffic on that port.
Slow page loads or API timeouts under load	Thread pool exhausted	Increase web.threads.maximum. Monitor with the internal metrics data source to verify thread utilization.
WebSocket disconnections in the browser	Idle timeout too short, or proxy not passing WebSocket	Increase web.websocket.maxIdleTimeout. If behind a proxy, add WebSocket upgrade headers (see Nginx example above).
"413 Request Entity Too Large" on file upload	Upload exceeds configured limit	Increase web.multipart.maxFileSize and web.multipart.maxRequestSize. If behind Nginx, also increase client_max_body_size.
Mango shows HTTP URLs even though the browser uses HTTPS	Forwarded headers not enabled	Set web.forwardedHeaders.enabled=true and ensure your reverse proxy sends X-Forwarded-Proto.
CORS errors in browser console	REST API blocking cross-origin requests	Enable rest.cors.enabled=true and add the requesting origin to rest.cors.allowedOrigins.

Related pages

• Mango properties guide -- Complete reference for all mango.properties settings
• Security configuration -- SSL/TLS certificate and keystore setup
• Performance tuning -- Diagnosing and resolving performance bottlenecks
• Installation overview -- Initial Mango setup and deployment options