AgileConfig Documentation

repository·master·Indexed 23 days ago

https://github.com/dotnetcore/agileconfig

A lightweight, distributed configuration center for .NET Core applications. AgileConfig provides real-time configuration updates via WebSocket, version management, and multi-environment support. It integrates with IConfiguration and IOptions patterns and supports multiple database providers including SqlServer, MySql, Sqlite, PostgreSql, Oracle, and MongoDB. The system consists of a .NET Standard 2.0 client library and a stateless node/management console deployable via Docker.

Tokens: 5.7K
Snippets: 18
Records: 26
Agent score: 82%

What's inside AgileConfig

Overview of AgileConfig
master
AgileConfig is a lightweight configuration center developed for .NET Core. It is designed for distributed and containerized applications to simplify reading and modifying configurations across multiple servers or containers. Unlike heavier alternatives like Apollo, AgileConfig focuses on simplicity, ease of deployment, and minimal learning curves. It can serve as a replacement for traditional webconfig or appsettings.json files.
Key Features:
- Simple Deployment: Supports Docker and requires minimal setup (can run with a single data node).
- High Availability: Supports multi-node distributed deployment; nodes are stateless, allowing horizontal scaling.
- Configuration Isolation: Supports isolation by Application and grouping within an application.
- Multi-Environment Support: Handles different deployment environments.
- Configuration Inheritance: Allows applications to inherit configurations from a common application.
- Real-time Updates: Uses WebSocket long-connections to push configuration changes to clients instantly.
- Seamless Integration: Supports IConfiguration and IOptions patterns, requiring minimal changes to existing .NET code.
- Resilience: If all nodes fail, clients can fall back to reading configurations from local file caches.
- Version Control: Supports configuration versioning and rollbacks.
- Extensibility: Supports Restful APIs, Service Registration/Discovery (v1.6.0+), SSO/OIDC (v1.7.0+), MongoDB storage (v1.9.0+), and OpenTelemetry (v1.9.4+).
https://github.com/dotnetcore/agileconfig/blob/master/README_CN.md
AgileConfig Architecture and Components
master
AgileConfig consists of three main components:
1. Client
A .NET Standard 2.0 library available via NuGet as agileconfig.client. It can be configured with multiple node addresses. Upon startup, the client randomly selects a node to establish a WebSocket long-connection. If a node fails, the client automatically attempts to reconnect to another configured node.
2. Nodes and Management Console
Built with ASP.NET Core. For simplicity, the management console and the node service are integrated into a single unit. The management console functionality can be enabled by configuring specific environment variables during startup.
3. Database
Used for persistent storage. AgileConfig uses Freesql as its data access component to provide robust support for multiple database types. Supported databases include:
- Relational: SqlServer, MySql, Sqlite, PostgreSql, Oracle.
- Non-Relational: mongodb.
High Availability Model: Nodes are stateless. If a single node goes offline, clients reconnect to other nodes. If all nodes go offline, clients rely on in-memory configurations (for already running clients) or local file caches (for new clients) to ensure application startup.
https://github.com/dotnetcore/agileconfig/blob/master/README_CN.md
Integrate Monaco Editor (AMD vs ESM)
master
Monaco Editor can be integrated into your application using either the AMD or ESM loading patterns.
- Use the ESM version (found in the esm directory) if you are using a module bundler like Webpack.
- Use the AMD version (found in the dev or min directories) if you are loading the editor via an AMD loader like loader.js or require.js.
Detailed integration guides are available in the ./docs/ directory of the package.
https://github.com/dotnetcore/agileconfig/blob/master/src/AgileConfig.Server.UI/react-ui-antd/public/monaco-editor/README.md
Explore the Monaco Editor API and Playground
master
You can interact with the editor's features and test customizations using the following resources:
- Playground: An interactive environment to try out the editor API and customizations: https://microsoft.github.io/monaco-editor/playground.html
- API Documentation: Full documentation of the editor's surface: https://microsoft.github.io/monaco-editor/api/index.html
- Monarch Playground: A tool to create custom Monarch tokenizers for new programming languages: https://microsoft.github.io/monaco-editor/monarch.html
https://github.com/dotnetcore/agileconfig/blob/master/src/AgileConfig.Server.UI/react-ui-antd/public/monaco-editor/README.md
Install dependencies for the Ant Design Pro UI
master
To prepare the environment for the Ant Design Pro project, install the required node_modules using either npm or yarn.
```
npm install
# or
yarn
```
https://github.com/dotnetcore/agileconfig/blob/master/src/AgileConfig.Server.UI/react-ui-antd/README.md
Manage the Ant Design Pro project with npm scripts
master
The project provides several scripts via package.json to manage the development lifecycle, including starting the development server, building for production, linting, and testing.
```
### Start project
```bash
npm start
```
Build project
```
npm run build
```
Check code style
```
npm run lint
```
Auto-fix lint errors
```
npm run lint:fix
```
Test code
```
npm test
```
https://github.com/dotnetcore/agileconfig/blob/master/src/AgileConfig.Server.UI/react-ui-antd/README.md
Install and Configure AgileConfig.Client
master
To use AgileConfig in a .NET application, install the client library via NuGet and configure the AgileConfig section in your appsettings.json.
Required configuration keys in appsettings.json:
- appId: The application ID.
- secret: The application secret.
- nodes: A comma-separated list of server node URLs (e.g., http://localhost:5000,http://localhost:5001).
- name: The client name.
- tag: An optional tag for the client.
- env: The environment name (e.g., dev).
```
Install-Package AgileConfig.Client
```
```
{
  "AgileConfig": {
    "appId": "app",
    "secret": "xxx",
    "nodes": "http://localhost:5000,http://localhost:5001",
    "name": "client_name",
    "tag": "tag1",
    "env": "dev"
  }
}
```
https://github.com/dotnetcore/agileconfig/blob/master/README.md
Pull AgileConfig Docker Image
master
If you are unable to pull images from Docker Hub due to network restrictions, you can use the Aliyun public registry:
```
docker pull registry.cn-shanghai.aliyuncs.com/kklldog/agile_config:latest
```
Or for the test version:
```
docker pull registry.cn-shanghai.aliyuncs.com/kklldog/agile_config:test
```
https://github.com/dotnetcore/agileconfig/blob/master/README_CN.md
Run the AgileConfig server via Docker
master
You can deploy an AgileConfig instance using Docker. The server requires three specific environment variables for configuration:
1. adminConsole: Set to true to enable the management console UI. If true, the instance serves as both a data node and the admin interface.
2. db__provider: Specifies the database type. Supported values: sqlserver, mysql, sqlite, PostgreSql, Oracle.
3. db__conn: The database connection string.
Note: If deploying via IIS or other methods, download the latest package from the releases page. If building from source, ensure the dist output from the react-ui-antd project is copied to apisite/wwwroot/ui.
```
sudo docker run \
--name agile_config \
-e TZ=Asia/Shanghai \
-e adminConsole=true \
-e db__provider=sqlite \
-e db__conn="Data Source=agile_config.db" \
-p 5000:5000 \
#-v /your_host_dir:/app/db \
-d kklldog/agile_config:latest
```
https://github.com/dotnetcore/agileconfig/blob/master/README_CN.md
Initialize the super administrator password
master
On the first run, you must initialize the super administrator password. The default username is fixed as admin.
https://github.com/dotnetcore/agileconfig/blob/master/README_CN.md
Install the monaco-editor npm module
master
To use the Monaco Editor in your project, install the monaco-editor package via npm. The package provides several distributions depending on your environment:
- esm: ESM version (recommended for bundlers like Webpack).
- dev: AMD bundled, non-minified version (recommended for development).
- min: AMD bundled, minified version (recommended for production).
- min-maps: Source maps for the min version.
The monaco.d.ts file defines the editor's public API and is the only part of the package guaranteed to be stable across releases.
```
$ npm install monaco-editor
```
https://github.com/dotnetcore/agileconfig/blob/master/src/AgileConfig.Server.UI/react-ui-antd/public/monaco-editor/README.md
Install the AgileConfig.Client NuGet package
master
The AgileConfig_Client is a .NET Core Standard 2.0 library used to integrate configuration management into your applications. Install it via NuGet:
```
Install-Package AgileConfig.Client
```
https://github.com/dotnetcore/agileconfig/blob/master/README_CN.md

AgileConfig Documentation

What's inside AgileConfig

1. Client

2. Nodes and Management Console

3. Database

Build project

Check code style

Auto-fix lint errors

Test code