Configuration - ChrisMavrommatis/Binacle.Net GitHub Wiki

Binacle.Net is designed for flexibility, with many optional features that can be activated as needed. Most features are specialized and reside within modules, which may have compatibility limitations depending on your stack, technologies, or databases.

Configuration files are located in the Config_Files folder, or in the container at /app/Config_Files.

Here’s the directory tree structure:

app
└── Config_Files
    β”œβ”€β”€ Features.json
    β”œβ”€β”€ Presets.json
    β”œβ”€β”€ DiagnosticsModule
    β”‚   β”œβ”€β”€ ConnectionStrings.json
    β”‚   β”œβ”€β”€ HeathChecks.json
    β”‚   └── Serilog.json
    β”œβ”€β”€ ServiceModule
    β”‚   β”œβ”€β”€ ConnectionStrings.json
    β”‚   β”œβ”€β”€ JwtAuth.json
    β”‚   β”œβ”€β”€ RateLimiter.json
    β”‚   └── Users.json
    └── UiModule
        └── ConnectionStrings.json

Binacle.Net’s modular architecture allows for additional functionality and customization options through its various modules.

Core

At its foundation, Binacle.Net provides the API functionality outlined in About the API. The core also supports customization of presets and includes the Swagger UI, which is disabled by default.

Presets

For instructions on customizing presets, see Configuration: Presets.

Swagger UI

To enable Swagger UI, you can either set the environment variable SWAGGER_UI=True or update the Features.json file as follows:

ο»Ώ{
  "Features": {
    "SERVICE_MODULE": "NotSet",
    "SWAGGER_UI": "True",
    "UI_MODULE": "NotSet"
  }
}

Customizing the Internal Port

By default, Binacle.Net runs on port 8080. To change the internal port within the container, you can specify a custom port using the ASPNETCORE_HTTP_PORTS environment variable.

For example, to run the application on port 80 inside the container:

docker run --name binacle-net -e ASPNETCORE_HTTP_PORTS=80 -e SWAGGER_UI=True -p 8080:80 binacle/binacle-net:latest

This allows flexibility in configuring the internal port according to your requirements.

Diagnostics Module

The Diagnostics Module offers logging, health checks, and telemetry. This module is always active and cannot be disabled, but individual featuresβ€”such as health checks and telemetryβ€”must be manually enabled. Logging is the default feature.

For detailed configuration instructions, see Configuration: Diagnostics Module.

Service Module

The Service Module is designed for public environments, introducing rate limiting on calculation endpoints and user authentication to allow authenticated users to bypass rate limits. This module requires a database to function.

For setup instructions, see Configuration: Service Module.

UI Module

The UI Module adds a user interface, including a visualizer demo for the Packing function, allowing users to see the packing process in action.

For detailed setup instructions, see Configuration: UI Module.

Typical Use Cases

While the Core and Diagnostics modules are fundamental to all deployments, other modules like the Service and UI modules may not be necessary in most environments. For example, public-facing features like rate limiting and user authentication are often unnecessary in controlled, internal systems. Similarly, the UI Module may not be needed if interactions with Binacle.Net are primarily through the API.

In many cases, Binacle.Net will likely be used primarily for its core API functionality and diagnostics, with other modules only activated based on specific needs, such as public API exposure or packing visualization.

Configuration

Binacle.Net offers flexible configuration options, allowing you to set values either through files or environment variables. Every configuration option available in a file can also be set as an environment variable. Refer to each specific module’s section for the relevant keys.

General Rule for Environment Variables

To pass file-based configuration values as environment variables, use a format with double underscores (__). For example, given the following JSON structure:

{
  "Examples": {
    "Example1": "example_value_1",
    "Example2": {
       "ExampleOption": "example_2_option"
    }
  }
}

To set the environment variable for Example1, the format would be:

Examples__Example1=example_value_1

For nested configurations like ExampleOption, use the same format, continuing to follow the hierarchy down the tree:

Examples__Example2__ExampleOption=example_2_option

[!WARNING]

Environment variables will always override the settings in configuration files. However, there are two exceptions to this rule:

  • Features: The settings in Features.json are not overridden by environment variables. Changes to features take immediate effect when set to true or false. Unlike other configurations, features do not follow a hierarchy; each feature is applied directly.
  • Connection Strings: Connection strings follow a different approach. Instead of using the double underscore format, they rely on specific environment variables. The environment variable serves as a fallback rather than overriding the connection string from the file. Be mindful of this when managing connections.

Conclusion

Binacle.Net's modular design allows you to tailor the API to your specific requirements. Whether you need enhanced diagnostics, public environment support, or a user-friendly interface for packing visualization, each module offers flexibility and can be enabled as needed. Refer to the relevant configuration guides to ensure a smooth setup and optimal functionality within your environment.