From 64b467d2024e4d393e3b30329973f0ec68bbd1a2 Mon Sep 17 00:00:00 2001 From: GreenJon902 <37347905+GreenJon902@users.noreply.github.com> Date: Fri, 21 Aug 2026 09:53:23 +0100 Subject: [PATCH 1/2] Added clarification on how konf maps section names with underscores --- docs/install.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/install.md b/docs/install.md index 91a40f72..17df0e47 100644 --- a/docs/install.md +++ b/docs/install.md @@ -10,7 +10,9 @@ Run into any issues? Join our [Discord](https://discord.gg/UxHnDWr) for support! ## Other Databases -Ledger supports other databases like MySQL, PostgreSQL and H2 with the help of the [Ledger Databases](https://www.curseforge.com/minecraft/mc-mods/ledger-databases) extension. +Ledger supports other databases like MySQL, PostgreSQL and H2 with the help of the [Ledger Databases](https://www.curseforge.com/minecraft/mc-mods/ledger-databases) extension. + +To set these as environment variables, [Konf](https://github.com/uchuhimo/konf) maps `database_extensions` to `DATABASEEXTENSIONS` (drops the underscore), e.g. set `DATABASEEXTENSIONS_PASSWORD=`. ### H2 H2 is another flat-file database like the default sqlite that may yield faster results but is more experimental. From 4896f28f532fffad94c397cc15372155c9a360de Mon Sep 17 00:00:00 2001 From: GreenJon902 Date: Fri, 21 Aug 2026 10:24:56 +0100 Subject: [PATCH 2/2] Updated structure of extensions doc and added ledger-databases doc --- docs/config.md | 245 ++++++++++++++-------------- docs/extensions/extensions.md | 34 ++-- docs/extensions/ledger-databases.md | 78 +++++++++ docs/install.md | 79 ++------- 4 files changed, 232 insertions(+), 204 deletions(-) create mode 100644 docs/extensions/ledger-databases.md diff --git a/docs/config.md b/docs/config.md index f919c214..75c32f77 100644 --- a/docs/config.md +++ b/docs/config.md @@ -1,122 +1,125 @@ -# Configuration - -Ledger's configuration file is found in `config/ledger.toml`. -It is written in [TOML](https://toml.io/en/) and can be edited in any text editor. -Any changes you make to the config will be automatically updated without needing to reload or restart the server. -When checking for the config for a value, it first checks the system properties, -then the system environment, then the config file and finally it will use the default. -For more info, read about [Konf](https://github.com/uchuhimo/konf). -To regenerate the config file, simply delete it. - -### Database settings - -Found under `[database]` - -`queueTimeoutMin` [Default: 5] is the maximum amount of time to wait for the queue to drain when the server stops in minutes - -`queueCheckDelaySec` [Default: 10] is the frequency in seconds to notify in console that the queue is not empty when the server stops - -`autoPurgeDays` [Default: -1] is the number of days to keep actions in the database. If set to -1, actions will never be purged automatically - -`batchSize` [Default: 1000] is the number of actions to insert into the database at once. -This can be increased to improve performance, but may cause issues with slow databases - -`batchDelay` [Default: 10] is the amount of time in ticks to wait between batches if the next batch isn't full. -This can be increased to improve performance, but may cause issues with slow databases - -`location` [Default: Nothing] is the location of the database file when using the default SQLite database or other file based databases like H2. -The path is relative to the server's root directory. If the path is left out, the database will default to the server's world directory. - -`logSQL` [Default: false] will log all SQL queries to the console. This is useful for debugging, but can be very spammy - -`updateSchema` [Default: false] will run updates old databases on startup when true. This can take a long time for large databases. -Current schema updates: Add actions_time index - -### Search settings - -Found under `[search]` - -`pageSize` [Default: 8] controls the number of actions displayed per page - -`purgePermissionLevel` [Default: 4] controls the permission level required to run the purge command - -`timeZone` [Default: "UTC"] sets the timezone to display timestamps in when hovered. -This uses the Java TimeZone format. You can provide offsets ("UTC", "UTC+3"), but the "continent/region" format is preferred. A full list can be found [here](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). - -`maxRange` [Default: 100] controls the maximum range allowed in rollback / restore - -### Message theme - -Found under `[color]` - -Ledger allows for the customisation of the colors used in the messages sent in game. -By default, Ledger uses the blue theme. More themes can be found in the [themes](themes.md) file - -### Filters - -These allow you to control what is and is not logged - -Found under `[actions]` - -All listed here are arrays and are formatted like so: -```toml -array = [] -blocks = ["minecraft:air", "minecraft:dirt"] -``` - -`typeBlacklist` [Default: empty] controls what action types are logged. Hover over the action in a chat message to see the type - -`worldBlacklist` [Default: empty] controls in which dimensions events are logged. - -`objectBlacklist` [Default: empty] controls which objects are logged. These can be item types, block types or entities - -`sourceBlacklist` [Default: empty] controls which sources are logged. Examples are `"lava"`, `"@playerName"` and `"gravity"`. Player names can be specified by prefixing them with `"@"` - -## Default Config -```toml -[database] -# The maximum amount of time to wait for the queue to drain when the server stops -queueTimeoutMin = 5 -# The amount of time between checking if the queue is empty when the server stops -queueCheckDelaySec = 10 - -[search] -# Number of actions to show per page -pageSize = 8 -# Permission level for purge command -purgePermissionLevel = 4 -# Time zone to display timestamps in. EX: "UTC", "UTC+1", "America/Los_Angeles" -timeZone = "UTC" - -[color] -# Colors in hex format -primary = "#009688" -primaryVariant = "#52c7b8" -secondary = "#1e88e5" -secondaryVariant = "#6ab7ff" -light = "#c5d6f0" - -[actions] -# Blacklists - blacklisted things will not be logged in the database -# Example - Prevent all actions with stone or bat as the object from being logged -# objectBlacklist = [ -# "minecraft:stone", -# "minecraft:bat" -# ] - -# Blacklists action types. Ex: "block-break", "entity-kill" -typeBlacklist = [] -# Blacklists worlds/dimensions. Ex: "mincraft:the_end", "minecraft:overworld" -worldBlacklist = [] -# Blacklists objects (Items, Mobs, Blocks). Ex: "minecraft:cobblestone", "minecraft:blaze" -objectBlacklist = [] -# Blacklists sources. Ex: "lava", "gravity", "fire", "fall", "@playerName" -sourceBlacklist = [] - -[networking] -# This section relates to Ledger's ability to interact with client mods for ease of use -# Networking is enabled by default but you can disable it here - -# Change to true to allow Ledger client mod packets -networking = true +# Configuration + +Ledger's configuration file is found in `config/ledger.toml`. +It is written in [TOML](https://toml.io/en/) and can be edited in any text editor. +Any changes you make to the config will be automatically updated without needing to reload or restart the server. +When checking for the config for a value, it first checks the system properties, +then the system environment, then the config file and finally it will use the default. +For more info, read about [Konf](https://github.com/uchuhimo/konf). +To regenerate the config file, simply delete it. + +### Database settings + +Found under `[database]` + +`queueTimeoutMin` [Default: 5] is the maximum amount of time to wait for the queue to drain when the server stops in minutes + +`queueCheckDelaySec` [Default: 10] is the frequency in seconds to notify in console that the queue is not empty when the server stops + +`autoPurgeDays` [Default: -1] is the number of days to keep actions in the database. If set to -1, actions will never be purged automatically + +`batchSize` [Default: 1000] is the number of actions to insert into the database at once. +This can be increased to improve performance, but may cause issues with slow databases + +`batchDelay` [Default: 10] is the amount of time in ticks to wait between batches if the next batch isn't full. +This can be increased to improve performance, but may cause issues with slow databases + +`location` [Default: Nothing] is the location of the database file when using the default SQLite database or other file based databases like H2. +The path is relative to the server's root directory. If the path is left out, the database will default to the server's world directory. + +`logSQL` [Default: false] will log all SQL queries to the console. This is useful for debugging, but can be very spammy + +`updateSchema` [Default: false] will run updates old databases on startup when true. This can take a long time for large databases. +Current schema updates: Add actions_time index + +### Search settings + +Found under `[search]` + +`pageSize` [Default: 8] controls the number of actions displayed per page + +`purgePermissionLevel` [Default: 4] controls the permission level required to run the purge command + +`timeZone` [Default: "UTC"] sets the timezone to display timestamps in when hovered. +This uses the Java TimeZone format. You can provide offsets ("UTC", "UTC+3"), but the "continent/region" format is preferred. A full list can be found [here](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). + +`maxRange` [Default: 100] controls the maximum range allowed in rollback / restore + +### Message theme + +Found under `[color]` + +Ledger allows for the customisation of the colors used in the messages sent in game. +By default, Ledger uses the blue theme. More themes can be found in the [themes](themes.md) file + +### Filters + +These allow you to control what is and is not logged + +Found under `[actions]` + +All listed here are arrays and are formatted like so: +```toml +array = [] +blocks = ["minecraft:air", "minecraft:dirt"] +``` + +`typeBlacklist` [Default: empty] controls what action types are logged. Hover over the action in a chat message to see the type + +`worldBlacklist` [Default: empty] controls in which dimensions events are logged. + +`objectBlacklist` [Default: empty] controls which objects are logged. These can be item types, block types or entities + +`sourceBlacklist` [Default: empty] controls which sources are logged. Examples are `"lava"`, `"@playerName"` and `"gravity"`. Player names can be specified by prefixing them with `"@"` + +### Extension config +Config for [extensions](extensions/extensions.md) should be placed in this file too. See relevant extension for options. + +## Default Config +```toml +[database] +# The maximum amount of time to wait for the queue to drain when the server stops +queueTimeoutMin = 5 +# The amount of time between checking if the queue is empty when the server stops +queueCheckDelaySec = 10 + +[search] +# Number of actions to show per page +pageSize = 8 +# Permission level for purge command +purgePermissionLevel = 4 +# Time zone to display timestamps in. EX: "UTC", "UTC+1", "America/Los_Angeles" +timeZone = "UTC" + +[color] +# Colors in hex format +primary = "#009688" +primaryVariant = "#52c7b8" +secondary = "#1e88e5" +secondaryVariant = "#6ab7ff" +light = "#c5d6f0" + +[actions] +# Blacklists - blacklisted things will not be logged in the database +# Example - Prevent all actions with stone or bat as the object from being logged +# objectBlacklist = [ +# "minecraft:stone", +# "minecraft:bat" +# ] + +# Blacklists action types. Ex: "block-break", "entity-kill" +typeBlacklist = [] +# Blacklists worlds/dimensions. Ex: "mincraft:the_end", "minecraft:overworld" +worldBlacklist = [] +# Blacklists objects (Items, Mobs, Blocks). Ex: "minecraft:cobblestone", "minecraft:blaze" +objectBlacklist = [] +# Blacklists sources. Ex: "lava", "gravity", "fire", "fall", "@playerName" +sourceBlacklist = [] + +[networking] +# This section relates to Ledger's ability to interact with client mods for ease of use +# Networking is enabled by default but you can disable it here + +# Change to true to allow Ledger client mod packets +networking = true ``` \ No newline at end of file diff --git a/docs/extensions/extensions.md b/docs/extensions/extensions.md index 62f96dc9..3bf4e01d 100644 --- a/docs/extensions/extensions.md +++ b/docs/extensions/extensions.md @@ -1,18 +1,18 @@ -# Extensions - -Ledger extensions allow for additional functionality to be added to Ledger via another mod - -## Install - -1. Install Ledger -2. Install the extension of your choice in your mods folder -3. Run your server and adjust the config as needed. The extension should provide information on how to configure it - -## Available extensions -- [Ledger Databases](https://www.curseforge.com/minecraft/mc-mods/ledger-databases) - Adds support for MySQL and H2 - -## Features possible via extensions - -- Changing the type of database used by Ledger -- Adding custom commands +# Extensions + +Ledger extensions allow for additional functionality to be added to Ledger via another mod + +## Install + +1. Install Ledger +2. Install the extension of your choice in your mods folder +3. Run your server and adjust the config as needed. The extension should provide information on how to configure it + +## Available extensions +- [Ledger Databases](https://www.curseforge.com/minecraft/mc-mods/ledger-databases) - Adds support for MySQL, H2, PostgreSQL, SQLite and MariaDB - [See documentation](ledger-databases.md). + +## Features possible via extensions + +- Changing the type of database used by Ledger +- Adding custom commands - Adding configuration options to the existing [config file](../config.md) \ No newline at end of file diff --git a/docs/extensions/ledger-databases.md b/docs/extensions/ledger-databases.md new file mode 100644 index 00000000..94eb0ad6 --- /dev/null +++ b/docs/extensions/ledger-databases.md @@ -0,0 +1,78 @@ +# Ledger Databases +Adds support for MySQL, MariaDB, H2, and PostgreSQL databases in Ledger. + +# Config +These settings can be appended to the bottom of the bottom of the [config file](../config.md). + +To set these as environment variables, [Konf](https://github.com/uchuhimo/konf) maps `database_extensions` to `DATABASEEXTENSIONS` (drops the underscore), e.g. set `DATABASEEXTENSIONS_PASSWORD=`. + +### H2 + +Add the following to the bottom of your Ledger config file: + +```toml +[database_extensions] +database = "H2" +``` + +### MySQL + +Add the following to the bottom of your Ledger config file: + +```toml +[database_extensions] +database = "MYSQL" +url = "" +username = "" +password = "" +properties = [] +maxPoolSize = 10 +connectionTimeout = 60000 +``` + +`url`: Must be URL of database with `/` appended. An example URL would be `localhost/ledger`. You can optionally add port information such as `localhost:3000/ledger` + +### MariaDB + +Add the following to the bottom of your Ledger config file: + +```toml +[database_extensions] +database = "MARIADB" +url = "" +username = "" +password = "" +properties = [] +maxPoolSize = 10 +connectionTimeout = 60000 +``` + +`url`: Must be URL of database with `/` appended. An example URL would be `localhost/ledger`. You can optionally add port information such as `localhost:3000/ledger` + +### PostgreSQL + +```toml +[database_extensions] +database = "POSTGRESQL" +url = "" +username = "" +password = "" +properties = [] +maxPoolSize = 10 +connectionTimeout = 60000 +``` + +### SQLite + +```toml +[database_extensions] +database = "SQLITE" +``` + +### Connector properties + +For some databases, such as MySQL, you can provide properties to the database connector. For each property, add a string entry to the `properties` array. + +```toml +properties = ["useJDBCCompliantTimezoneShift=true", "useLegacyDatetimeCode=false", "serverTimezone=UTC"] +``` \ No newline at end of file diff --git a/docs/install.md b/docs/install.md index 17df0e47..892c8b88 100644 --- a/docs/install.md +++ b/docs/install.md @@ -1,66 +1,13 @@ -# Installation - -1. Set up a [Fabric Server](https://fabricmc.net/wiki/tutorial:installing_minecraft_fabric_server) for 1.17 -2. Install [Fabric API](https://www.curseforge.com/minecraft/mc-mods/fabric-api) -3. Install [Fabric Language Kotlin](https://www.curseforge.com/minecraft/mc-mods/fabric-language-kotlin/) -4. Install [Ledger](https://www.curseforge.com/minecraft/mc-mods/ledger) -5. Run the server -6. Adjust [config](config.md) as needed - -Run into any issues? Join our [Discord](https://discord.gg/UxHnDWr) for support! - -## Other Databases -Ledger supports other databases like MySQL, PostgreSQL and H2 with the help of the [Ledger Databases](https://www.curseforge.com/minecraft/mc-mods/ledger-databases) extension. - -To set these as environment variables, [Konf](https://github.com/uchuhimo/konf) maps `database_extensions` to `DATABASEEXTENSIONS` (drops the underscore), e.g. set `DATABASEEXTENSIONS_PASSWORD=`. - -### H2 -H2 is another flat-file database like the default sqlite that may yield faster results but is more experimental. - -Add the following to the bottom of your Ledger config file: - -```toml -[database_extensions] -database = "H2" -``` - -### MySQL -MySQL requires running a separate MySQL database and more setup than just plug and play SQLite, but can support much larger databases at faster speeds. -It also supports MySQL based databases like MariaDB. - -Add the following to the bottom of your Ledger config file: - -```toml -[database_extensions] -database = "MYSQL" -url = "" -username = "" -password = "" -properties = [] -``` - -`url`: Must be URL of database with `/` appended. An example URL would be `localhost/ledger`. You can optionally add port information such as `localhost:3000/ledger` - -### PostgreSQL -PostgreSQL requires running a separate PostgreSQL database and more setup than just plug and play SQLite, but can support much larger databases at faster speeds. It is more experimental the MySQL but may yield faster performance. - -Add the following to the bottom of your Ledger config file: - -```toml -[database_extensions] -database = "POSTGRESQL" -url = "" -username = "" -password = "" -properties = [] -``` - -`url`: Must be URL of database with `/` appended. An example URL would be `localhost/ledger`. You can optionally add port information such as `localhost:3000/ledger` - -## Connector properties - -For some databases, such as MySQL, you can provide properties to the database connector. For each property, add a string entry to the `properties` array. - -```toml -properties = ["useJDBCCompliantTimezoneShift=true", "useLegacyDatetimeCode=false", "serverTimezone=UTC"] -``` +# Installation + +1. Set up a [Fabric Server](https://fabricmc.net/wiki/tutorial:installing_minecraft_fabric_server) for 1.17 +2. Install [Fabric API](https://www.curseforge.com/minecraft/mc-mods/fabric-api) +3. Install [Fabric Language Kotlin](https://www.curseforge.com/minecraft/mc-mods/fabric-language-kotlin/) +4. Install [Ledger](https://www.curseforge.com/minecraft/mc-mods/ledger) +5. Run the server +6. Adjust [config](config.md) as needed + +Run into any issues? Join our [Discord](https://discord.gg/UxHnDWr) for support! + +## Other Databases +Ledger supports other databases like MySQL, PostgreSQL and H2 with the help of the [Ledger Databases](https://www.curseforge.com/minecraft/mc-mods/ledger-databases) extension.