document config

istudyatuni · Aug 16, 2024 · a3e68eb · a3e68eb
1 parent d900bc4
commit a3e68eb
Show file tree

Hide file tree

Showing 5 changed files with 79 additions and 54 deletions.
diff --git a/.env.sample b/.env.sample
diff --git a/config.toml b/config.toml
diff --git a/docs/config.md b/docs/config.md
@@ -0,0 +1,74 @@
+## Configuration
+
+You can configure everything via plain environment variables, `.env` or `config.toml`. Precedence of configuration: env > config.
+
+| Description                                  | Env                  | Default                        | Note                                        |
+|:---------------------------------------------|:---------------------|:-------------------------------|:--------------------------------------------|
+| Server port                                  | `PORT`               | 8080                           | Do not change when using docker compose     |
+| Prefix for admin API<sup>1</sup>             | `ADMIN_API`          | -                              | Optional. If not provided, API is disabled  |
+| If should allow new registers                | `ALLOW_NEW_REGISTER` | `true`                         |                                             |
+| Limit for JSON payload for requests          | `LIMITS_JSON`        | 4MiB<sup>2</sup>               | Original server has no limit                |
+| Secret text for encoding/decoding JWT tokens | `JWT_SECRET`         | -                              | Required                                    |
+| JWT issuer                                   | -                    | `http://0.0.0.0:8080/`         |                                             |
+| JWT audience                                 | -                    | `http://0.0.0.0:8080/resource` |                                             |
+| Path to database file                        | `DATABASE_URL`       | data.db                        | For SQLite                                  |
+| Name of database in MySQL                    | `DATABASE_NAME`      | kotatsu_db                     | For MySQL                                   |
+| Host of MySQL database                       | `DATABASE_HOST`      | localhost                      | For MySQL                                   |
+| Port of MySQL database                       | `DATABASE_PORT`      | 3306                           | For MySQL                                   |
+| User for connecting to MySQL database        | `DATABASE_USER`      | -                              | For MySQL. Required                         |
+| Password for user in MySQL database          | `DATABASE_PASSWORD`  | -                              | For MySQL. Required                         |
+| Log level                                    | `RUST_LOG`           | `error`<sup>3</sup>            | Only plain environment variable (no `.env`) |
+
+1. Enables some additiional features, like statistics. For `/admin` URL will look like `http://IP/admin/stats`
+1. Examples: 256 kB, 0.500 mib, 1MB, 1GiB
+1. Possible values: `off`, `error`, `warn`, `info`, `debug`, `trace`. In debug build default `info`
+
+### Example `.env`
+
+```bash
+# mysql
+DATABASE_NAME=kotatsu_db
+DATABASE_HOST=localhost
+DATABASE_PORT=3306
+DATABASE_USER=YOUR_USER
+DATABASE_PASSWORD=YOUR_PASSWORD
+
+# sqlite
+DATABASE_URL=data.db
+
+PORT=8080
+JWT_SECRET=SECRET
+ALLOW_NEW_REGISTER=true
+ADMIN_API=/admin
+LIMITS_JSON=4MiB
+```
+
+### Example `config.toml`
+
+Currently name of config file can't be configured.
+
+```toml
+[server]
+port = 8080
+admin_api = "/admin"
+allow_new_register = true
+
+[server.limits]
+json = "4MiB"
+
+[db]
+# sqlite
+url = "data.db"
+
+# mysql
+name = "kotatsu_db"
+host = "localhost"
+port = 3306
+user = "YOUR_USER"
+password = "YOUR_PASSWORD"
+
+[jwt]
+secret = ""
+issuer = "http://0.0.0.0:8080/"
+audience = "http://0.0.0.0:8080/resource"
+```
diff --git a/docs/install.md b/docs/install.md
@@ -1,5 +1,7 @@
 ## Running
 
+See description of configuration variables in [config.md](config.md)
+
 ### With docker-compose
 
 Download [`docker-compose.yaml`](https://github.com/istudyatuni/kotync/blob/master/docs/docker-compose.yml):
@@ -8,12 +10,7 @@ Download [`docker-compose.yaml`](https://github.com/istudyatuni/kotync/blob/mast
 curl -L https://github.com/istudyatuni/kotync/raw/master/docs/docker-compose.yml -o docker-compose.yml
 ```
 
-After that fill environment variables inside. Some notes:
-
-- VERSION can be `dev`, or the version itself, like `0.1.0`. See all tags [here](https://github.com/istudyatuni/kotync/pkgs/container/kotync).
-- ADMIN_API is optional path prefix to enable some additiional features, like statistics. URL will look like `http://IP/ADMIN_API/stats`
-- RUST_LOG - set level of logging
-- LIMITS_JSON - change limit for JSON payload for requests. Examples: `256 kB`, `0.500 mib`, `1MB`, `1GiB`
+After that fill environment variables inside. Note: VERSION can be `dev`, or the version itself, like `0.1.0`. See all tags [here](https://github.com/istudyatuni/kotync/pkgs/container/kotync).
 
 Then run:
 
@@ -53,8 +50,6 @@ docker run -d -p 8081:8080 \
 
 `VERSION` - see [above](#with-docker-compose).
 
-See up-to-date list of environment variables in [`.env.sample`](./.env.sample).
-
 ### Note on MySQL
 
 ***When using `docker`***
@@ -117,10 +112,6 @@ cross b --release --target=x86_64-unknown-linux-musl
 cargo b --release --no-default-features --features=original --target=x86_64-unknown-linux-musl
 ``` -->
 
-## Configuring
-
-You can configure everything via `config.toml`. Also you can set some values via `.env` or plain environment variables, see `.env.sample` for available options. Precedence of configuration: env > config.
-
 <!-- ## Running
 
 ### Single binary (systemd)

diff --git a/src/config.rs b/src/config.rs
@@ -2,6 +2,8 @@ use std::fmt::Display;
 
 use rocket::data::ByteUnit;
 
+// When add new values here also update docs/docker-compose.yaml and
+// docs/config.md
 #[derive(Debug, Clone, confique::Config)]
 pub struct Conf {
     #[config(nested)]