admin: Initial quota docs

2024-11-23 17:59:25 -05:00 · 2024-10-15 23:09:46 +02:00 · 2024-10-15 23:09:46 +02:00 · bfd9913680
commit bfd9913680
parent c132e28383
3 changed files with 168 additions and 0 deletions
--- 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`: **\<empty\>**: 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
--- 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/)
--- a/docs/admin/quota.md
+++ 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/<GROUPNAME>/users/<USERNAME>" -XPUT
+```
+
+Or remove them:
+
+```sh
+api_helper "/admin/quota/groups/<GROUPNAME>/users/<USERNAME>" -XDELETE
+```