WebLedger

This project is a convenience and simple .NET Web Ledger Server & Cli.

Environment Requirement

.NET 8 SDK is required for development or compiling the source, and the binary could be native-ready

Usage

Prepare Database

You need a MySQL server $host deployed, and an account $user with $pwd with access on schema $dbname.

Variables here is just for easy description.

Deploy Server

docker pull hitrefresh/web-ledger:0.3.1 
# if you are in China, login and use aliyun mirror: 
# docker pull registry.cn-hangzhou.aliyuncs.com/hitrefresh/web-ledger:0.3.1
# and tag
# docker tag registry.cn-hangzhou.aliyuncs.com/hitrefresh/web-ledger:0.3.1 hitrefresh/web-ledger:0.3.1
docker run -tid \
  --name ledger \
  --restart always \
  -p <port>:8080 \
  -e WL_SQL_DB='<dbname>' \
  -e WL_SQL_HOST='<host>' \
  -e WL_SQL_HOST='<user>' \
  -e WL_SQL_PWD='<pwd>' \
  hitrefresh/web-ledger:0.3.1

Start CLI (Direct)

docker pull hitrefresh/web-ledger-cli:0.3.1
# if you are in China, login and use aliyun mirror: 
# docker pull registry.cn-hangzhou.aliyuncs.com/hitrefresh/web-ledger-cli:0.3.1
# and tag
# docker tag registry.cn-hangzhou.aliyuncs.com/hitrefresh/web-ledger-cli:0.3.1 hitrefresh/web-ledger-cli:0.3.1
docker run --rm -i\
  --name ledger-cli \
  -e WL_METHOD='mysql' \
  -e WL_SQL_DB='<dbname>' \
  -e WL_SQL_HOST='<host>' \
  -e WL_SQL_HOST='<user>' \
  -e WL_SQL_PWD='<pwd>' \
  hitrefresh/web-ledger-cli:0.3.1

And then you can configure the access.

Start CLI (Remote)

docker pull hitrefresh/web-ledger-cli:0.3.1 
# if you are in China, login and use aliyun mirror: 
# docker pull registry.cn-hangzhou.aliyuncs.com/hitrefresh/web-ledger-cli:0.3.1
# and tag
# docker tag registry.cn-hangzhou.aliyuncs.com/hitrefresh/web-ledger-cli:0.3.1 hitrefresh/web-ledger-cli:0.3.1
docker run --rm -i \
  --name ledger-cli \
  -e WL_METHOD='http' \
  -e WL_HOST='<http-or-https-url>' \
  -e WL_ACCESS='<access>' \
  -e WL_SECRET='<secret>' \
  hitrefresh/web-ledger-cli:0.3.1

And then you can configure the access.

For Developers

Build Image

cd web
dotnet publish --os linux /t:PublishContainer
cd cli
dotnet publish --os linux /t:PublishContainer

Deployment/Initialize

Assuming you already have the binaries.

Prepare Database

You need a MySQL server $host deployed, and an account $user with $pwd with access on schema $dbname.

Variables here is just for easy description.

Configuration

Server

The server use appsettings.json at runtime and appsettings.development.json at develop time.

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "ConnectionStrings": {
    "mysql": "server=$host; port=3306; database=$dbname; user=$user; password=$pwd; Persist Security Info=False; Connect Timeout=300"
  },
  "AllowedHosts": "*"
}

Normally, the only thing you need to customize is the connection string.

CLI Client

CLI use config.json as configuration file. There are two ways for the client to connect with WebLegder Server, through HTTP, or directly through mysql connection.

• For Mysql Connection, just make the connection string as the server's.:

{
  "target": "mysql",
  "host": "server=$host; port=3306; database=$dbname; user=$user; password=$pwd; Persist Security Info=False; Connect Timeout=300"
}

• For Http Connection, access and secret are part of the authorization, which will be explained later:

{
  "target": "http",
  "host": "http://localhost:5143",
  "access": "root",
  "secret": "5jH!3NNF$HQs@KV2Q427HnN0RXgCeA$w"
}

Authorization

Generate initial access and secret

1. Connect to the database using CLI.
2. Use ls command to view all available CLI commands.
3. Usels-acc command to view all accesses.
4. Use grant <access-name> to create new access, and store the secret; replace <access-name> with whatever you like.

How to use?

• To use access and secret for CLI client, just edit the configuration as said previously
• To use them for your own Http client, configure your http client as following; to develop them, you can take cli/services/*Manager.cs as reference:

http.BaseAddress = new(builder.Configuration["host"]);
http.DefaultRequestHeaders.Add("wl-access", builder.Configuration["access"]);
http.DefaultRequestHeaders.Add("wl-secret", builder.Configuration["secret"]);

Concepts

Category

The category of a ledger entry, such as "daily necessities", "daily chemicals", "food", "beverages", can have an optional parent category.

Type

A specific type of ledger entry, such as "cola," "shampoo," or "bread," represents a specific type rather than a type or category of income/consumption, and is associated with a category when it first appears (default category thereafter).

Entry

A ledger entry, has its Category, Type, Amount, GivenTime, etc.

View

A summarized report for certain categories in a certain time range, it can only be created from View Templates.

View Template

Describe a class of reports (View) for certain categories, which store the categories information.

View Automation

Automation to create View from View Template every year/day/week/month/quarter(3 months).

Usage

Functions can be accessed through CLI or other clients, for development server, you can view /swagger to get OpenApi Support.

Notice: Use ls to view CLI commands.