From c06a49e81c440e19c4e91466c3992b023c462a5b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Dachary?= Date: Wed, 9 Aug 2023 23:26:16 +0200 Subject: [PATCH 1/6] docs: admin: storage: the defaut root for storage is APP_DATA_PATH --- admin/storage.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/admin/storage.md b/admin/storage.md index d0bdf45e..69036acb 100644 --- a/admin/storage.md +++ b/admin/storage.md @@ -7,7 +7,7 @@ The storage for each subsystem (`attachments`, `lfs`, `avatars`, `repo-avatars`, `repo-archive`, `packages`, `actions_log`, `actions_artifact`) is defined in `app.ini`. It can either be on disk (`local`) or using a MinIO server (`minio`). The default is `local` -storage, using the following hierarchy under the `WORK_PATH` directory: +storage, using the following hierarchy under the `APP_DATA_PATH` directory: | storage | default base path | app.ini sections | | ----------------- | ------------------ | -------------------------------------------------- | @@ -20,7 +20,7 @@ storage, using the following hierarchy under the `WORK_PATH` directory: | actions_log | actions_log/ | [actions_log] or [storage.actions_log] | | actions_artifacts | actions_artifacts/ | [actions_artifacts] or [storage.actions_artifacts] | -For instance if `WORK_PATH` was `/appdata`, the default directory to +For instance if `APP_DATA_PATH` was `/appdata`, the default directory to store attachments would be `/appdata/attachements`. ## Overriding the defaults @@ -78,9 +78,9 @@ PATH = /mystorage If the value of PATH for the `XXXX` subsystem is relative, it is constructed as follows: -- The default base path is `WORK_PATH` (for instance `/appdata`) -- If `[storage].PATH` is relative (for instance `storage`), the default base path becomes `WORK_PATH`/`[storage].PATH` (for instance `/appdata/storage`) -- If `[storage.XXXX].PATH` is relative, the path becomes `WORK_PATH`/`[storage].PATH`/`[storage.XXXX].PATH` (for instance`/appdata/storage/lfs`) +- The default base path is `APP_DATA_PATH` (for instance `/appdata`) +- If `[storage].PATH` is relative (for instance `storage`), the default base path becomes `APP_DATA_PATH`/`[storage].PATH` (for instance `/appdata/storage`) +- If `[storage.XXXX].PATH` is relative, the path becomes `APP_DATA_PATH`/`[storage].PATH`/`[storage.XXXX].PATH` (for instance`/appdata/storage/lfs`) It is recommended to always set the `PATH` values to an absolute path name because it is easier to understand and maintain. From 69843f60cd1d718aa3f523b289fe513830e5ee56 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Dachary?= Date: Thu, 10 Aug 2023 00:04:59 +0200 Subject: [PATCH 2/6] docs: admin: storage: do not document [storage.XXXX] its behavior is not thoroughly tested and varies in ways that are confusing --- admin/storage.md | 49 ++++++++++++++++++++++++------------------------ 1 file changed, 24 insertions(+), 25 deletions(-) diff --git a/admin/storage.md b/admin/storage.md index 69036acb..2c878e11 100644 --- a/admin/storage.md +++ b/admin/storage.md @@ -9,16 +9,16 @@ The storage for each subsystem (`attachments`, `lfs`, `avatars`, (`local`) or using a MinIO server (`minio`). The default is `local` storage, using the following hierarchy under the `APP_DATA_PATH` directory: -| storage | default base path | app.ini sections | -| ----------------- | ------------------ | -------------------------------------------------- | -| attachments | attachments/ | [attachments] or [storage.attachements] | -| lfs | lfs/ | [lfs] or [storage.lfs] | -| avatars | avatars/ | [avatars] or [storage.avatars] | -| repo-avatars | repo-avatars/ | [repo-avatars] or [storage.repo-avatars] | -| repo-archive | repo-archive/ | [repo-archive] or [storage.repo-archive] | -| packages | packages/ | [packages] or [storage.packages] | -| actions_log | actions_log/ | [actions_log] or [storage.actions_log] | -| actions_artifacts | actions_artifacts/ | [actions_artifacts] or [storage.actions_artifacts] | +| storage | default base path | app.ini sections | +| ----------------- | ------------------ | ------------------- | +| attachments | attachments/ | [attachments] | +| lfs | lfs/ | [lfs] | +| avatars | avatars/ | [avatars] | +| repo-avatars | repo-avatars/ | [repo-avatars] | +| repo-archive | repo-archive/ | [repo-archive] | +| packages | packages/ | [packages] | +| actions_log | actions_log/ | [actions_log] | +| actions_artifacts | actions_artifacts/ | [actions_artifacts] | For instance if `APP_DATA_PATH` was `/appdata`, the default directory to store attachments would be `/appdata/attachements`. @@ -35,22 +35,19 @@ PATH = /mystorage would change the default for storing attachements to `/mystorage/attachments`. It is also possible to change these settings -for each subsystem in a `[storage.XXXX]` section. For instance setting: +for each subsystem in a `[XXXX]` section. For instance setting: ``` [storage] PATH = /mystorage -[storage.attachments] +[attachments] PATH = /otherstorage/attachements ``` would store attachments in `/otherstorage/attachements` while `lfs` files would be stored in `/mystorage/lfs`. -Finally, instead of using `[storage.XXXX]` it is also possible to use -`[XXXX]` as a shorthand. - ## Storage type The value of `STORAGE_TYPE` can be `local` (the default) or `minio`. For instance: @@ -80,7 +77,6 @@ constructed as follows: - The default base path is `APP_DATA_PATH` (for instance `/appdata`) - If `[storage].PATH` is relative (for instance `storage`), the default base path becomes `APP_DATA_PATH`/`[storage].PATH` (for instance `/appdata/storage`) -- If `[storage.XXXX].PATH` is relative, the path becomes `APP_DATA_PATH`/`[storage].PATH`/`[storage.XXXX].PATH` (for instance`/appdata/storage/lfs`) It is recommended to always set the `PATH` values to an absolute path name because it is easier to understand and maintain. @@ -88,7 +84,7 @@ name because it is easier to understand and maintain. ## `minio` storage When the `STORAGE_TYPE` is set to `minio`, the settings available in -all sections (`[storage]`, `[storage.XXXX]` and `[XXXX]`) are: +all sections (`[storage]` and `[XXXX]`) are: - `SERVE_DIRECT`: **false**: Allows the storage driver to redirect to authenticated URLs to serve files directly. Only supported via signed URLs. - `MINIO_ENDPOINT`: **localhost:9000**: Minio endpoint to connect. @@ -99,7 +95,7 @@ all sections (`[storage]`, `[storage.XXXX]` and `[XXXX]`) are: - `MINIO_USE_SSL`: **false**: Minio enabled ssl. - `MINIO_INSECURE_SKIP_VERIFY`: **false**: Minio skip SSL verification. -One setting is only available in the `[storage.XXXX]` or `[XXXX]` sections: +One setting is only available in the `[XXXX]` sections: - `MINIO_BASE_PATH`: defaults to the `default base path` of the `XXXX` subsystem (see the table above) and is a relative path within the @@ -109,21 +105,24 @@ One setting is only available in the `[storage.XXXX]` or `[XXXX]` sections: The sections in which a setting is found have the following priority: -- [XXXX] is first -- [storage.XXXX] is second -- [storage] is last +- [XXXX] has precedence +- [storage] is the default For instance: ``` [storage] -PATH = /last - -[storage.attachments] -PATH = /second +PATH = /default [attachments] PATH = /first ``` Will set the value of `PATH` for attachements to `/first`. + +## Undocumented features + +It is **strongly** recommended to avoid using undocumented features +(such as `[storage.attachments]` as an alternative to `[attachements]` +for instance) because their behavior is not thoroughly tested and may +lead to unexpected results. From 13e1c388d706c9c504af489832cfbd07adc4e6a3 Mon Sep 17 00:00:00 2001 From: Earl Warren Date: Thu, 10 Aug 2023 08:20:03 +0200 Subject: [PATCH 3/6] docs: admin: config-cheat-sheet: remove references to [storage.xxxx] --- admin/config-cheat-sheet.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/admin/config-cheat-sheet.md b/admin/config-cheat-sheet.md index 0cfce0e0..ce81482f 100644 --- a/admin/config-cheat-sheet.md +++ b/admin/config-cheat-sheet.md @@ -771,7 +771,7 @@ Define allowed algorithms and their minimum key length (use -1 to disable a type - `DISABLE_GRAVATAR`: **false**: Enable this to use local avatars only. **DEPRECATED [v1.18+]** moved to database. Use admin panel to configure. - `ENABLE_FEDERATED_AVATAR`: **false**: Enable support for federated avatars (see -- `AVATAR_STORAGE_TYPE`: **default**: Storage type defined in `[storage.xxx]`. Default is `default` which will read `[storage]` if no section `[storage]` will be a type `local`. +- `AVATAR_STORAGE_TYPE`: **default**: Storage type [as explained in detail in the storage documentation](../storage/). - `AVATAR_UPLOAD_PATH`: **data/avatars**: Path to store user avatar image files. - `AVATAR_MAX_WIDTH`: **4096**: Maximum avatar image width in pixels. - `AVATAR_MAX_HEIGHT`: **4096**: Maximum avatar image height in pixels. @@ -779,7 +779,7 @@ Define allowed algorithms and their minimum key length (use -1 to disable a type - `AVATAR_MAX_ORIGIN_SIZE`: **262144** (256KiB): If the uploaded file is not larger than this byte size, the image will be used as is, without resizing/converting. - `AVATAR_RENDERED_SIZE_FACTOR`: **2**: The multiplication factor for rendered avatar images. Larger values result in finer rendering on HiDPI devices. -- `REPOSITORY_AVATAR_STORAGE_TYPE`: **default**: Storage type defined in `[storage.xxx]`. Default is `default` which will read `[storage]` if no section `[storage]` will be a type `local`. +- `REPOSITORY_AVATAR_STORAGE_TYPE`: **default**: Storage type defined [as explained in detail in the storage documentation](../storage/). - `REPOSITORY_AVATAR_UPLOAD_PATH`: **data/repo-avatars**: Path to store repository avatar image files. - `REPOSITORY_AVATAR_FALLBACK`: **none**: How Forgejo deals with missing repository avatars - none = no avatar will be displayed @@ -1208,16 +1208,16 @@ WARNING: Changing the settings below can break federation. ## Storage (`storage`) -| storage | default base path | app.ini sections | -| ----------------- | ------------------ | -------------------------------------------------- | -| attachments | attachments/ | [attachments] or [storage.attachements] | -| lfs | lfs/ | [lfs] or [storage.lfs] | -| avatars | avatars/ | [avatars] or [storage.avatars] | -| repo-avatars | repo-avatars/ | [repo-avatars] or [storage.repo-avatars] | -| repo-archive | repo-archive/ | [repo-archive] or [storage.repo-archive] | -| packages | packages/ | [packages] or [storage.packages] | -| actions_log | actions_log/ | [actions_log] or [storage.actions_log] | -| actions_artifacts | actions_artifacts/ | [actions_artifacts] or [storage.actions_artifacts] | +| storage | default base path | app.ini sections | +| ----------------- | ------------------ | ------------------- | +| attachments | attachments/ | [attachments] | +| lfs | lfs/ | [lfs] | +| avatars | avatars/ | [avatars] | +| repo-avatars | repo-avatars/ | [repo-avatars] | +| repo-archive | repo-archive/ | [repo-archive] | +| packages | packages/ | [packages] | +| actions_log | actions_log/ | [actions_log] | +| actions_artifacts | actions_artifacts/ | [actions_artifacts] | The storage configuration for attachments, lfs, avatars, repo-avatars, repo-archive, packages, actions_log, actions_artifact is [explained in detail in a dedicated section](../storage/). From fd669862e61b3d22462f19f28e25d86af1448002 Mon Sep 17 00:00:00 2001 From: Caesar Schinas Date: Thu, 10 Aug 2023 09:38:52 +0100 Subject: [PATCH 4/6] docs: s/attachements/attachments/ # Conflicts: # v1.20/admin/config-cheat-sheet.md # v1.21/admin/storage.md --- admin/storage.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/admin/storage.md b/admin/storage.md index 2c878e11..1b105015 100644 --- a/admin/storage.md +++ b/admin/storage.md @@ -21,7 +21,7 @@ storage, using the following hierarchy under the `APP_DATA_PATH` directory: | actions_artifacts | actions_artifacts/ | [actions_artifacts] | For instance if `APP_DATA_PATH` was `/appdata`, the default directory to -store attachments would be `/appdata/attachements`. +store attachments would be `/appdata/attachments`. ## Overriding the defaults @@ -33,7 +33,7 @@ section. For instance setting: PATH = /mystorage ``` -would change the default for storing attachements to +would change the default for storing attachments to `/mystorage/attachments`. It is also possible to change these settings for each subsystem in a `[XXXX]` section. For instance setting: @@ -42,10 +42,10 @@ for each subsystem in a `[XXXX]` section. For instance setting: PATH = /mystorage [attachments] -PATH = /otherstorage/attachements +PATH = /otherstorage/attachments ``` -would store attachments in `/otherstorage/attachements` while `lfs` +would store attachments in `/otherstorage/attachments` while `lfs` files would be stored in `/mystorage/lfs`. ## Storage type @@ -57,7 +57,7 @@ The value of `STORAGE_TYPE` can be `local` (the default) or `minio`. For instanc STORAGE_TYPE = minio ``` -Will use `minio` for all subsystems (`attachements`, `lfs`, etc.) +Will use `minio` for all subsystems (`attachments`, `lfs`, etc.) instead of storing them on disk. Each storage type has its own settings, as explained below. @@ -118,11 +118,11 @@ PATH = /default PATH = /first ``` -Will set the value of `PATH` for attachements to `/first`. +Will set the value of `PATH` for attachments to `/first`. ## Undocumented features It is **strongly** recommended to avoid using undocumented features -(such as `[storage.attachments]` as an alternative to `[attachements]` +(such as `[storage.attachments]` as an alternative to `[attachments]` for instance) because their behavior is not thoroughly tested and may lead to unexpected results. From 41ee7cc748305a45239f8fe5f051af72023650dc Mon Sep 17 00:00:00 2001 From: Earl Warren Date: Thu, 10 Aug 2023 11:04:42 +0200 Subject: [PATCH 5/6] docs: admin: [attachments] is actually [attachment] So it actually is [attachment] or [storage.attachments], one singular and one plural. One more reason to **not** document [storage.XXXX]. # Conflicts: # v1.21/admin/config-cheat-sheet.md # v1.21/admin/storage.md --- admin/config-cheat-sheet.md | 16 ++++++++-------- admin/storage.md | 29 +++++++++++++++-------------- 2 files changed, 23 insertions(+), 22 deletions(-) diff --git a/admin/config-cheat-sheet.md b/admin/config-cheat-sheet.md index ce81482f..71d429a5 100644 --- a/admin/config-cheat-sheet.md +++ b/admin/config-cheat-sheet.md @@ -1210,14 +1210,14 @@ WARNING: Changing the settings below can break federation. | storage | default base path | app.ini sections | | ----------------- | ------------------ | ------------------- | -| attachments | attachments/ | [attachments] | -| lfs | lfs/ | [lfs] | -| avatars | avatars/ | [avatars] | -| repo-avatars | repo-avatars/ | [repo-avatars] | -| repo-archive | repo-archive/ | [repo-archive] | -| packages | packages/ | [packages] | -| actions_log | actions_log/ | [actions_log] | -| actions_artifacts | actions_artifacts/ | [actions_artifacts] | +| Attachments | attachments/ | [attachment] | +| LFS | lfs/ | [lfs] | +| Avatars | avatars/ | [avatars] | +| Repo avatars | repo-avatars/ | [repo-avatars] | +| Repo archives | repo-archive/ | [repo-archive] | +| Packages | packages/ | [packages] | +| Actions logs | actions_log/ | [actions_log] | +| Actions Artifacts | actions_artifacts/ | [actions_artifacts] | The storage configuration for attachments, lfs, avatars, repo-avatars, repo-archive, packages, actions_log, actions_artifact is [explained in detail in a dedicated section](../storage/). diff --git a/admin/storage.md b/admin/storage.md index 1b105015..db9df18c 100644 --- a/admin/storage.md +++ b/admin/storage.md @@ -11,14 +11,14 @@ storage, using the following hierarchy under the `APP_DATA_PATH` directory: | storage | default base path | app.ini sections | | ----------------- | ------------------ | ------------------- | -| attachments | attachments/ | [attachments] | -| lfs | lfs/ | [lfs] | -| avatars | avatars/ | [avatars] | -| repo-avatars | repo-avatars/ | [repo-avatars] | -| repo-archive | repo-archive/ | [repo-archive] | -| packages | packages/ | [packages] | -| actions_log | actions_log/ | [actions_log] | -| actions_artifacts | actions_artifacts/ | [actions_artifacts] | +| Attachments | attachments/ | [attachment] | +| LFS | lfs/ | [lfs] | +| Avatars | avatars/ | [avatars] | +| Repo avatars | repo-avatars/ | [repo-avatars] | +| Repo archives | repo-archive/ | [repo-archive] | +| Packages | packages/ | [packages] | +| Actions logs | actions_log/ | [actions_log] | +| Actions Artifacts | actions_artifacts/ | [actions_artifacts] | For instance if `APP_DATA_PATH` was `/appdata`, the default directory to store attachments would be `/appdata/attachments`. @@ -41,7 +41,7 @@ for each subsystem in a `[XXXX]` section. For instance setting: [storage] PATH = /mystorage -[attachments] +[attachment] PATH = /otherstorage/attachments ``` @@ -114,7 +114,7 @@ For instance: [storage] PATH = /default -[attachments] +[attachment] PATH = /first ``` @@ -122,7 +122,8 @@ Will set the value of `PATH` for attachments to `/first`. ## Undocumented features -It is **strongly** recommended to avoid using undocumented features -(such as `[storage.attachments]` as an alternative to `[attachments]` -for instance) because their behavior is not thoroughly tested and may -lead to unexpected results. +It is **strongly** recommended to avoid using undocumented features - +such as `[storage.attachments]` as an alternative to `[attachment]` +for instance (the plural is not a typo, it is a unification problem) - +because their behavior is not thoroughly tested and may lead to +unexpected results. From dd92764a36cf6c3ff6c6532a76514f8ea87da7f3 Mon Sep 17 00:00:00 2001 From: Earl Warren Date: Thu, 10 Aug 2023 18:28:16 +0200 Subject: [PATCH 6/6] docs: admin: storage: fix sections names # Conflicts: # v1.21/admin/config-cheat-sheet.md # v1.21/admin/storage.md --- admin/config-cheat-sheet.md | 46 +++++++++++++++++++------- admin/storage.md | 65 ++++++++++++++++++++++--------------- 2 files changed, 74 insertions(+), 37 deletions(-) diff --git a/admin/config-cheat-sheet.md b/admin/config-cheat-sheet.md index 71d429a5..39f9b84f 100644 --- a/admin/config-cheat-sheet.md +++ b/admin/config-cheat-sheet.md @@ -801,6 +801,8 @@ Default templates for project boards: - `MAX_SIZE`: **4**: Maximum size (MB). - `MAX_FILES`: **5**: Maximum number of attachments that can be uploaded at once. +Additional settings can be included in this section to specify where the data is stored, as [explained in detail in the storage documentation](../storage/). + ## Log (`log`) - `ROOT_PATH`: **\**: Root path for log files. @@ -1198,6 +1200,8 @@ WARNING: Changing the settings below can break federation. - `LIMIT_SIZE_SWIFT`: **-1**: Maximum size of a Swift upload (`-1` means no limits, format `1000`, `1 MB`, `1 GiB`) - `LIMIT_SIZE_VAGRANT`: **-1**: Maximum size of a Vagrant upload (`-1` means no limits, format `1000`, `1 MB`, `1 GiB`) +Additional settings can be included in this section to specify where the data is stored, as [explained in detail in the storage documentation](../storage/). + ## Mirror (`mirror`) - `ENABLED`: **true**: Enables the mirror functionality. Set to **false** to disable all mirrors. Pre-existing mirrors remain valid but won't be updated; may be converted to regular repo. @@ -1206,20 +1210,40 @@ WARNING: Changing the settings below can break federation. - `DEFAULT_INTERVAL`: **8h**: Default interval between each check - `MIN_INTERVAL`: **10m**: Minimum interval for checking. (Must be >1m). +## LFS (`lfs`) + +Settings can be included in this section to specify where the LFS files are stored, as [explained in detail in the storage documentation](../storage/). + +## Repository Avatars (`repo-avatar`) + +Settings can be included in this section to specify where the repository avatars are stored, as [explained in detail in the storage documentation](../storage/). + +## Avatars (`avatar`) + +Settings can be included in this section to specify where the avatars are stored, as [explained in detail in the storage documentation](../storage/). + +## Actions logs (`storage.actions_log`) + +Settings can be included in this section to specify where the actions logs are stored, as [explained in detail in the storage documentation](../storage/). + +## Actions Artifacts (`storage.artifacts`) + +Settings can be included in this section to specify where the actions artifacts are stored, as [explained in detail in the storage documentation](../storage/). + ## Storage (`storage`) -| storage | default base path | app.ini sections | -| ----------------- | ------------------ | ------------------- | -| Attachments | attachments/ | [attachment] | -| LFS | lfs/ | [lfs] | -| Avatars | avatars/ | [avatars] | -| Repo avatars | repo-avatars/ | [repo-avatars] | -| Repo archives | repo-archive/ | [repo-archive] | -| Packages | packages/ | [packages] | -| Actions logs | actions_log/ | [actions_log] | -| Actions Artifacts | actions_artifacts/ | [actions_artifacts] | +| subsystem | default base path | app.ini sections | +| ------------------- | ------------------ | --------------------- | +| Attachments | attachments/ | [attachment] | +| LFS | lfs/ | [lfs] | +| Avatars | avatars/ | [avatar] | +| Repository avatars | repo-avatars/ | [repo-avatar] | +| Repository archives | repo-archive/ | [repo-archive] | +| Packages | packages/ | [packages] | +| Actions logs | actions_log/ | [storage.actions_log] | +| Actions Artifacts | actions_artifacts/ | [actions.artifacts] | -The storage configuration for attachments, lfs, avatars, repo-avatars, repo-archive, packages, actions_log, actions_artifact is [explained in detail in a dedicated section](../storage/). +The settings for all these sections are [explained in detail in the storage documentation](../storage/). ## Proxy (`proxy`) diff --git a/admin/storage.md b/admin/storage.md index db9df18c..7fdc2929 100644 --- a/admin/storage.md +++ b/admin/storage.md @@ -3,25 +3,23 @@ title: 'Storage settings' license: 'CC-BY-SA-4.0' --- -The storage for each subsystem (`attachments`, `lfs`, `avatars`, -`repo-avatars`, `repo-archive`, `packages`, `actions_log`, -`actions_artifact`) is defined in `app.ini`. It can either be on disk +The storage for each subsystem is defined in `app.ini`. It can either be on disk (`local`) or using a MinIO server (`minio`). The default is `local` storage, using the following hierarchy under the `APP_DATA_PATH` directory: -| storage | default base path | app.ini sections | -| ----------------- | ------------------ | ------------------- | -| Attachments | attachments/ | [attachment] | -| LFS | lfs/ | [lfs] | -| Avatars | avatars/ | [avatars] | -| Repo avatars | repo-avatars/ | [repo-avatars] | -| Repo archives | repo-archive/ | [repo-archive] | -| Packages | packages/ | [packages] | -| Actions logs | actions_log/ | [actions_log] | -| Actions Artifacts | actions_artifacts/ | [actions_artifacts] | +| subsystem | default base path | app.ini sections | +| ------------------- | ------------------ | --------------------- | +| Attachments | attachments/ | [attachment] | +| LFS | lfs/ | [lfs] | +| Avatars | avatars/ | [avatar] | +| Repository avatars | repo-avatars/ | [repo-avatar] | +| Repository archives | repo-archive/ | [repo-archive] | +| Packages | packages/ | [packages] | +| Actions logs | actions_log/ | [storage.actions_log] | +| Actions Artifacts | actions_artifacts/ | [actions.artifacts] | For instance if `APP_DATA_PATH` was `/appdata`, the default directory to -store attachments would be `/appdata/attachments`. +store attachments will be `/appdata/attachments`. ## Overriding the defaults @@ -33,9 +31,9 @@ section. For instance setting: PATH = /mystorage ``` -would change the default for storing attachments to +will change the default for storing attachments to `/mystorage/attachments`. It is also possible to change these settings -for each subsystem in a `[XXXX]` section. For instance setting: +for each subsystem in their dedicated section. For instance: ``` [storage] @@ -45,8 +43,8 @@ PATH = /mystorage PATH = /otherstorage/attachments ``` -would store attachments in `/otherstorage/attachments` while `lfs` -files would be stored in `/mystorage/lfs`. +will store attachments in `/otherstorage/attachments` while `lfs` +files will be stored in `/mystorage/lfs`. ## Storage type @@ -57,14 +55,18 @@ The value of `STORAGE_TYPE` can be `local` (the default) or `minio`. For instanc STORAGE_TYPE = minio ``` -Will use `minio` for all subsystems (`attachments`, `lfs`, etc.) +will use `minio` for all subsystems (Attachments, LFS, etc.) instead of storing them on disk. Each storage type has its own settings, as explained below. ## `local` storage There is just one setting when the `STORAGE_TYPE` is set to `local`, -`PATH`. For instance: +`PATH`. It must be an absolute path and is interpreted as follows. + +In the `[storage]` section, `PATH` is the directory under which the default +base path of each subsystem will be created instead of +`APP_DATA_PATH`. For instance, if `APP_DATA_PATH` equals `/appdata`: ``` [storage] @@ -72,14 +74,25 @@ STORAGE_TYPE = local PATH = /mystorage ``` -If the value of PATH for the `XXXX` subsystem is relative, it is -constructed as follows: +Will create attachments in `/mystorage/attachments` instead of +`/appdata/attachments`, LFS files in `/mystorage/lfs` instead of +`/appdata/lfs`, etc. -- The default base path is `APP_DATA_PATH` (for instance `/appdata`) -- If `[storage].PATH` is relative (for instance `storage`), the default base path becomes `APP_DATA_PATH`/`[storage].PATH` (for instance `/appdata/storage`) +In the section dedicated to a subsystem (see the table above), `PATH` +is the base path under which all files will be stored. For instance: -It is recommended to always set the `PATH` values to an absolute path -name because it is easier to understand and maintain. +``` +[storage] +STORAGE_TYPE = local +PATH = /mystorage + +[attachment] +STORAGE_TYPE = local +PATH = /otherstorage/attachments +``` + +will store attachments in `/otherstorage/attachments` while `lfs` +files will be stored in `/mystorage/lfs`. ## `minio` storage