Introduction

Welcome to the Grux documentation! Grux is a high-performance web server designed to handle modern web workloads with exceptional speed and efficiency.

📚 What you'll learn

This documentation covers everything from installation to advanced configuration. Whether you're migrating from Apache or Nginx, or setting up a new server, you'll find all the information you need here.

System Requirements

  • Linux, macOS, or Windows
  • Minimum 256MB RAM
  • 64-bit processor

Installation

Grux can be installed on various platforms using different methods.

Choose the one that best fits your environment.

Go to getting started guide for each platform

Configuration

Grux uses a SQLite database located in /db to store its configuration. Filename is called grux.db.

Configuration Basics

Starting a fresh Grux will generate a default configuration, so you can get up and running quickly.

This generates a basic config that will listen on port 80 for http, and port 443 for https and port 8000 for the admin portal.

It was also generate two basic default sites. One that will be served on port 80 and 443, which is just the default Grux site and one for the admin portal on port 8000.

Automatic self-signed certificates for SSL/TLS

Grux will automatically generate self-signed certificates for your domains, if they do not have a certificate present. Make sure to replace them with proper valid certificates for the site hostnames.

Configuration Bindings

Bindings in the configuration defines which IP addresses and ports the server will listen on for new connections.

The most common are port 80 for HTTP and port 443 for HTTPS, but other may be relevant. Like port 8000 for admin portal in Grux.

Listening on all interfaces

Grux will listen on all available network interfaces by default. This means it will accept connections on any IP address assigned to the server.

This is the case when IP 0.0.0.0 is used.

If you had multiple network interfaces, you could bind to a specific one by using its IP address.

Configuration Sites

Sites in Grux are defined by their domain names (hostnames). Each site can have its own configuration settings, including document root, SSL certificates, and more.

Each site can be mapped to one or more bindings, so a single site can be served on multiple ports or IP addresses.

To default or not to default

A site can be configured as a default site, which means it will be served when no other site matches the request.

If you do not want a response for a hostnames that you do not served, just do not have any sites marked as default. Then Grux will just show HTTP 404 Not Found for any unknown hostnames.

How sites are matched

Grux uses a first match simple algorithm to determine which site should handle a request. This means that the first site configuration that matches the request's hostname and port will be used. Or the default in the end if nothing else matches.

Rewrite Functions

Grux supports rewrite functions that allow you to modify incoming requests before they are processed. This can be useful for URL rewriting, redirection, and other request manipulations.

Rewrite functions can be defined per site, allowing for granular control over how requests are handled.

All rewrite functions are pre-defined and therefore very easy to use and add to a site.

By default, Grux only serves static files that exist on the file system.

Currently supported rewrite functions are:

  • OnlyWebRootIndexForSubdirs: Checks if request is a file that exist, if so, serve that. Otherwise redirect request to index file in the web root, which for PHP can be index.php in the web root. This rewrite rule is required for WordPress, Laravel etc. to work. Essentially needed for web sites that handle all the page routing it self, such as WordPress routing all requests through index.php.

Site specific HTTP headers

You can define custom HTTP headers to be included in the response for a specific site. This allows you to add security headers, caching directives, or any other headers that are relevant to your site.

These headers will be included in every response served for that site and consist of key-value pairs that you specify in the site configuration.

Server Settings

Server settings are simple key/value settings, that control various aspects of the server's behavior.

These settings apply globally to all sites and bindings by default, but may be overridden per site or binding.

Global Settings

Grux offers various server-wide settings that can be configured to optimize performance, security, and behavior.

Operation Mode

Grux operation mode controls the level of logging and debugging information generated during runtime. Different modes can be set to optimize for development or production environments. Production mode is the default and the state is stored in the database. Operation mode can be changed in two ways: from the admin portal in the menu or by using the command line option.

Available operation modes:

  • SPEEDTEST: Speed test mode with no logging for optimal performance.
  • PRODUCTION: Production mode with minimal logging for high performance. This is the default mode.
  • DEBUG: Development mode with debug logging for debugging purposes.
  • DEV: Development mode with trace level logging for development purposes.

Usage

Learn which commands Grux supports.

To get the commandline options currently supported by Grux, you can use the following command:

grux --help

Get the current version:

grux --version

Command line arguments

Grux supports various command line arguments to control its behavior and configuration.

Controlling operation mode

You can set the operation mode directly from the command line when starting Grux, by using the -o or --opmode argument followed by the desired mode.

Examples:

grux -o PRODUCTION
grux --opmode DEV

This will start Grux in the specified operation mode, overriding the mode set in the database for that session. It may still be changed from the admin portal when running, even after being set on the command line.

Exporting the current configuration

You can use command line to export the current configuration to a file for backup or transfer purposes. It will be exported to the specified file path and in JSON format.

Examples:

grux -e my_config.json
grux --export-conf ./config/my_config.json

Importing a configuration

You can use command line to import a configuration from a file. This is useful for restoring a backup or transferring settings from another Grux instance.

Examples:

grux -i my_config.json
grux --import-conf ./config/my_config.json

Reset admin password

The password for user 'admin' can be reset using the command line, if it was forgotten or for other reasons need to be changed. The new password will be displayed in the console output after running the command.

Examples:

grux --reset-admin-password

Advanced Topics

Performance Tuning

By default, a few of the performance options are turned off. You can enable them for better performance.

Gzip Compression

The most basic to enable is gzip compression of files, which can significantly reduce the size of responses and improve loading times. In combination with the file cache, this is a great addition, as compression only happens each time a file is cached and not on each request.

File caching

Then we have the game-changer for serving static files: file caching. By enabling file caching, you can drastically reduce the load on your server and improve response times for clients. The file cache keeps the file state and content in memory, making it able to serve files as fast as it is possible to push the bits through the cable, without having to hit the disk every time.

But, there is a downside to file caching

File caching will consume a certain amount of memory, especially if you have a large number of files or files that change frequently. Monitor your server's memory usage and adjust the cache size as needed.

File caching expects files not to change frequently. If your files are updated often, consider using a different caching strategy.

An internal thread in Grux will monitor the cached files for changes, and update the cache as needed, but this will NOT be instantaneous, so a delay may occur when updating files.

Logging

System logging

Per default, Grux logs very little about the runtime requests, unless errors happen.

Grux will generate a system.log in the /logs dir, which will log startup messages and any errors/problems that happen.

Access logging

You can enable access logging per site, to log each request made to that site will get logged to the location mapped in the site configuration.

Trace logging - detailed logging

For development or bug tracking purposes, trace logging can be enabled to provide more detailed logs.

This is done by running Grux with the -o DEV option:

grux -o DEV

Beware: When starting in DEV mode, logs are cleared on Grux startup.

This generates a lot of log output, which can be useful for debugging but will also impact performance.

Export/Import Configuration

Grux allows you to export and import the server configuration using command line arguments. This is useful for backing up your settings or transferring them to another Grux instance.

See the command line documentation on how to export Grux configuration and import the configuration again.

Troubleshooting

If you are having request/response trouble, check the section about logging and enable trace logging for more details.

Common Issues

Port Already in Use

Problem: Error message "address already in use"

Solution: Check if another process is using the port:

Change the port in your configuration or stop the conflicting process.

Configuration not loading due to errors

Problem: Grux can not start due to configuration errors

Solution: Edit the database directly in /db/grux.db with a SQLite client to fix any issues.

Alternative Solution: Backup and delete the grux.db from /db and restart Grux, which restores default settings.

Contributing

We welcome contributions from the community!

Here's how you can help:

Ways to Contribute

  • Report bugs and request features on GitHub Issues
  • Improve documentation
  • Submit pull requests with bug fixes