Core Settings
Core settings are global Gruxi settings that control various aspects of the server behavior.
These settings apply globally to all sites and bindings by default, but may be overridden per site or binding.
Base Settings
Settings related to the basic operation of the Gruxi server.
Max Connection Duration
Defines the maximum duration in seconds a connection can remain open. Connections exceeding this duration will be force closed by the server. This helps prevent resource exhaustion from long-lived connections.
Users will not see an explicit error; the connection simply closes, and the client will open a new one if it needs to make more requests.
Max Body Size
Defines the maximum allowed size for request bodies. Requests with bodies exceeding this size will be rejected with a 413 Payload Too Large response.
This setting helps prevent abuse and resource exhaustion by limiting the size of incoming request bodies. You should adjust this value based on the expected size of requests your server will handle.
Blocked File Patterns
A list of file extension patterns that should be blocked from being served by Gruxi. Requests for files matching these patterns will receive a 404 Not Found response. You can adapt this list to your security needs and the types of files you want to restrict access to. The primary consumer of this list is the static file processor, but other processors may also respect these settings.
Admin Portal
The admin portal settings control the behavior of the Gruxi admin portal.
Domain Name
The domain is used to access the admin portal. You can set this to a specific domain or leave it empty to allow access from any domain. This is useful for security, to restrict access to the admin portal to specific domains only. For TLS, the domain should be set to a valid domain name that matches the TLS certificate you want for the admin portal.
Enable Automatic TLS
Enables automatic TLS certificate acquisition and renewal via Let's Encrypt for the admin portal. When enabled, Gruxi will automatically obtain and renew TLS certificates for the specified domain using Let's Encrypt. Make sure that the domain is correctly set and points to the Gruxi server for this to work.
TLS Certificate Path
If automatic TLS is not used, you can specify the path to a custom TLS certificate file here for the admin portal. If automatic TLS is enabled, this setting will be ignored.
TLS Key Path
If automatic TLS is not used, you can specify the path to a custom TLS key file here for the admin portal. If automatic TLS is enabled, this setting will be ignored.
Unauthenticated Access to Admin Portal
Controls whether users can access the admin portal without logging in. When enabled, users can access the admin portal without authentication. This is useful during local development or testing, but it is not recommended for production environments due to the obvious security risk.
Telemetry
Controls the collection of telemetry data for performance monitoring and usage statistics.
Bearer Token
The bearer token is used for authenticating clients to retrieve telemetry data from the Gruxi server. This token should be kept secret and only shared with trusted clients that need access to telemetry data. Once it is set, clients must include this token in the Authorization header of their requests to access telemetry endpoints. For example:
Authorization: Bearer <your_token>
This is handled by most libraries automatically when you set the token in the client configuration, so you typically won't need to manually add the header.
Empty bearer token
Beware that if the token is empty, the telemetry endpoints will not be accessible and port 8001 will be closed, so make sure to set a valid token if you want to use telemetry features.
Caching
Caching in a web server is the master of performance. It can significantly improve response times and reduce server load by storing frequently accessed data in memory or on disk.
General Caching Settings
Allow Short-Lived Caches when File Cache is Disabled
When enabled, Gruxi will allow short-lived caches for files even when the file cache is disabled. This can improve performance for frequently accessed files by allowing clients to cache them for a short duration, reducing the number of requests to the server.
File Cache Settings
The file cache is an important mechanism to improve performance by caching accessed files in memory.
This reduces disk I/O and speeds up file serving for accessed files.
It’s important to configure it properly to avoid excessive memory usage and ensure optimal performance. Especially for servers with limited memory, careful configuration of the file cache is crucial.
When compression is also active, the compressed version of the file is stored in cache to avoid recompressing on each request.
Enable File Caching
Enable or disable the file caching mechanism. When enabled, accessed files will be cached in memory for faster subsequent access.
Max Cached Files/Directories
The maximum number of files or directories to aim for in the cache. When the number of cached items reaches this limit, the cache will start evicting files that have exceeded their maximum time in cache to free up space.
Max Size Per File (MB)
The maximum size of a single file to be cached. Files larger than this size will not be cached. This helps prevent large files from consuming excessive memory in the cache.
Max Time To Keep a File (seconds)
Defines the maximum time a file can remain in the cache. Files that have been in the cache longer than this duration will be evicted to free up space for new files. This helps ensure that the cache remains fresh and does not hold onto stale content.
HTTP Caching Settings
Enable HTTP Caching Headers
When enabled, Gruxi will add HTTP caching headers to responses to help clients cache content effectively. This can improve performance for repeat visitors by allowing browsers to cache static resources. Currently, Gruxi adds these headers for static file responses only:
Cache-Control:
public, max-age=31536000for static files (js, css, fonts, images, video, audio etc.), indicating that they can be cached for one year.no-cachefor .html files, indicating that browsers should always check for a fresh version.public, max-age=86400for other file types, indicating they can be cached for one day.
ETag header based on the file's last modified time and size, allowing clients to validate cached content.
Expires header is added to all files served by the static file processor, and the value is set to one year from today.
Last-Modified header based on the file's last modified time.
HTTP Caching headers are only added for the static file processor
This is intentional because Gruxi should not modify dynamic content generated by other processors, such as another web server or a scripting engine like PHP. Those processors are best left to handle their own caching headers as appropriate. You can force headers by adding them explicitly in your site's configuration if needed.
Gruxi supports conditional requests
This support is based on ETag and Last-Modified headers for static files, which specifically is:
If-Match(RFC 7232 Section 3.1)If-None-Match(RFC 7232 Section 3.2)If-Modified-Since(RFC 7232 Section 3.3)If-Unmodified-Since(RFC 7232 Section 3.4)
INFO
All the caching headers can be overridden by explicitly setting them in your site's configuration.
Gzip Compression
Compression of responses can significantly reduce the amount of data transferred over the network, improving load times and reducing bandwidth usage. Used in conjunction with file caching, it can greatly enhance performance for clients that support compressed responses, as it will cache the compressed version of the file in memory.
Enable Gzip Compression
Enables Gzip compression for responses. When enabled, Gruxi will compress responses using Gzip for clients that support it, reducing bandwidth usage and improving load times.
Compressible Content Types
Only responses with content types matching these patterns will be compressed. This allows you to specify which types of content should be compressed, such as text-based formats like HTML, CSS, and JavaScript. This is the default list, but you can modify it to suit your needs.
TLS with LetsEncrypt
LetsEncrypt Account Email
Email address used for Let’s Encrypt account registration and notifications globally on this Gruxi server. This email will be used by Let’s Encrypt to send important information about your certificates, such as expiration reminders.
Use LetsEncrypt Staging Server
When enabled, Gruxi will use the Let’s Encrypt staging server for obtaining TLS certificates. This is useful for testing and development purposes, as it allows you to obtain test certificates without hitting rate limits on the production Let’s Encrypt servers.
WARNING
Certificates obtained from the staging server are not trusted by browsers and will result in security warnings.
Be sure to disable this setting when moving to production to obtain valid certificates.
Logging
Controls how Gruxi does log rotation.
Enable Log Rotation
Allows Gruxi to automatically rotate log files when they reach a certain size or age. This helps manage disk space and keeps log files organized.
Rotate By Size
When enabled, log files will be rotated when they reach a specified size in megabytes. This helps prevent log files from growing indefinitely and consuming too much disk space.
Max Log File Size (MB)
Defines the maximum size in megabytes that a log file can reach before it is rotated when Rotate By Size is enabled. When a log file exceeds this size, it will be archived and a new log file will be created.
Rotate By Time
When enabled, log files will be rotated based on a specified time interval (e.g., daily, weekly). This helps keep log files organized by time and prevents them from growing too large.
Rotation Interval
Defines the time interval for log rotation when Rotate By Time is enabled. Common intervals include daily, weekly, or monthly. For example, setting it to "daily" will rotate the log file every day at midnight.
Delete Old Logs
When enabled, Gruxi will automatically delete old log files that exceed a specified age. This helps manage disk space by removing logs that are no longer needed.
Max Log Age (days)
Defines the maximum age in days that log files will be kept when Delete Old Logs is enabled. Log files older than this age will be automatically deleted. For example, setting it to 30 will keep logs for 30 days and delete any logs older than that.