mirror of
https://codeberg.org/forgejo/docs.git
synced 2024-11-20 17:26:56 -05:00
admin: Initial quota docs
This commit is contained in:
Otto Richter
parent
c132e28383
commit
bfd9913680
3 changed files with 168 additions and 0 deletions
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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/)
|
||||
|
|
|
|||
138
docs/admin/quota.md
Normal file
138
docs/admin/quota.md
Normal file
|
|
@ -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
|
||||
```
|
||||
Loading…
Reference in a new issue