From bfd9913680aa359780c6f49b6e4dd6d5656662f4 Mon Sep 17 00:00:00 2001 From: Otto Richter Date: Tue, 15 Oct 2024 23:09:46 +0200 Subject: [PATCH] admin: Initial quota docs --- docs/admin/config-cheat-sheet.md | 29 +++++++ docs/admin/index.md | 1 + docs/admin/quota.md | 138 +++++++++++++++++++++++++++++++ 3 files changed, 168 insertions(+) create mode 100644 docs/admin/quota.md diff --git a/docs/admin/config-cheat-sheet.md b/docs/admin/config-cheat-sheet.md index 1f2cd9a2..90b49e4c 100644 --- a/docs/admin/config-cheat-sheet.md +++ b/docs/admin/config-cheat-sheet.md @@ -1288,6 +1288,35 @@ Settings can be included in this section to specify where the actions artifacts The settings for all these sections are [explained in detail in the storage documentation](../storage/). +## Quota (`quota`) + +Also see the [dedicated docs about the quota feature](../quota/). + +- `ENABLED`: **false**: Enable quota feature. +- `DEFAULT_GROUPS`: **\**: Comma-separated list of groups that apply by default to users. These groups can be configured via the API. + +### Default Quota (`quota.default`) + +- `TOTAL`: **-1**: Size for the default quota group. `-1` means unlimited storage. Can be suffixed with units, e.g. `500M` or `2G`. + +### Quota subjects (list) + +The available subjects for the quota feature are: + +- `size:all`: The total size of everything Forgejo tracks. +- `size:git:all`: The total size of all Git data (including all repositories, and LFS). + - `size:git:lfs`: The size of all Git LFS data (either in private or public repos). + - `size:repos:all`: The total size of all repositories (not including LFS). + - **NOT YET AVAILABLE** `size:repos:public`: The total size of all public repositories (not including LFS). + - **NOT YET AVAILABLE** `size:repos:private`: The total size of all private repositories (not including LFS). +- `size:assets:all`: The size of all assets tracked by Forgejo. + - `size:assets:attachments:all`: The size of all kinds of attachments tracked by Forgejo. + - `size:assets:attachments:issues`: Size of all attachments attached to issues, including issue comments. + - `size:assets:attachments:releases`: Size of all attachments attached to releases. This does _not_ include automatically generated archives. + - `size:assets:artifacts`: Size of all Action artifacts. + - `size:assets:packages:all`: Size of all Packages. +- `size:wiki`: Wiki size + ## Proxy (`proxy`) - `PROXY_ENABLED`: **false**: Enable the proxy if true, all requests to external via HTTP will be affected, if false, no proxy will be used even environment http_proxy/https_proxy diff --git a/docs/admin/index.md b/docs/admin/index.md index 799bbca5..32df53d0 100644 --- a/docs/admin/index.md +++ b/docs/admin/index.md @@ -27,3 +27,4 @@ These documents are targeted to people who run Forgejo on their machines. - [Adopt existing git directories](./adopt/) - [Interface customization](./customization/) - [OAuth2 provider](./oauth2-provider/) +- [Soft-Quota](./quota/) diff --git a/docs/admin/quota.md b/docs/admin/quota.md new file mode 100644 index 00000000..3fbc04ea --- /dev/null +++ b/docs/admin/quota.md @@ -0,0 +1,138 @@ +--- +title: 'Soft-Quota' +license: 'CC-BY-SA-4.0' +--- + +Forgejo has early support for a soft-quota that can protect your server from high disk usage +due to abuse or errors. +The feature is still in development. +If you make use of it, consider sending us feedback via [a discussion](https://codeberg.org/forgejo/discussions/issues/), +or the Matrix channels. + +## Understanding soft-quota and its limitations + +Forgejo has chosen to use a "soft" quota implementation. +It means that Forgejo checks the quota usage only before an action is executed, +but it will allow a started action to complete. + +In some cases (like pushing to Git repositories), +it is hard to estimate the exact new size, +because it depends on how much data is available and how much we can benefit from compression. +As a result, it is possible to exceed the quota if the operation was started before the quota was used up, +but after the quota is exceeded, +new operations that would increase the quota won't be possible. + +Further, there is currently little support for early prevention of operations in the UI: +The handling for e.g. web operations that are denied later is not yet optimal. + +You can read more about the technical background in the +[initial PR setting the foundations](https://codeberg.org/forgejo/forgejo/pulls/4212). + +## Getting started + +The quota feature is currently not yet enabled by default. +Set this in your app.ini: + +```ini +[quota] +ENABLED = true +``` + +You can now choose between managing quota via the config file +(simple option, but limited functionality) +or via the API (more advanced). + +### Simple case + +To make use of a simple quota for your instance, +you can set a global quota for all data: + +```ini +[quota.default] +TOTAL = 2G +``` + +`quota.default.TOTAL` is `-1` (unlimited) by default and can take sizes suffixed with units such as 500M or 10G. + +## Advanced usage: via API + +If you have more complex needs, +you can use the API to configure quota rules. + +1. With an admin account, create a new application token. +2. Make yourself familiar with the API endpoints by visiting the swagger documentation (e.g. by visiting `/api/swagger` ([online example](https://v9.next.forgejo.org/api/swagger#/admin)). +3. Make yourself familiar with the available quota subjects from the [respective section in the config cheat sheet](../config-cheat-sheet/#quota-subjects-list). +4. Optionally, set up a local helper for interacting with the API: + +```sh + export FORGEJO_API_TOKEN="your-admin-api-token" # delete after setting it up or ensure it is not preserved in the shell history +api_helper() { + endpoint="$1"; shift + curl -s -H "content-type: application/json" \ + -H "accept: application/json" \ + -H "authorization: token ${FORGEJO_API_TOKEN}" \ + "https://url-to-your-forgejo/api/v1${endpoint}" "$@" | jq . +} +``` + +### Example: Set up a quota group + +This example sets a quota group that is restricted tightly on Git repo space, +has more generous limits for LFS files +and can store unlimited packages and attachments, +but Actions artifacts are restricted: + +```json +{ + "name": "newgroup", + "rules": [ + { + "name": "git", + "limit": 200000000, + "subjects": ["size:repos:all"] + }, + { + "name": "git-lfs", + "limit": 500000000, + "subjects": ["size:git:lfs"] + }, + { + "name": "all-assets", + "limit": -1, + "subjects": ["size:assets:all"] + }, + { + "name": "size:assets:artifacts", + "limit": 350000000, + "subjects": ["size:assets:all"] + } + ] +} +``` + +After tuning the above JSON to your needs, +you can create a new quota group by calling the API: + +```sh +api_helper /admin/quota/groups -XPOST -d '{"your": "json"}' +``` + +Check the API documentation for more details on how you can add, modify and delete quota groups and their rules. + +### Example: Managing users + +If you do not modify the `default` quota group, +or have your new groups listed in the `[quota].DEFAULT_GROUPS` list, +they won't apply to users. + +However, you can create quota groups and assign users to them: + +```sh +api_helper "/admin/quota/groups//users/" -XPUT +``` + +Or remove them: + +```sh +api_helper "/admin/quota/groups//users/" -XDELETE +```