Refactor path system #10879

New Issue

GiteaMirror · 2025-11-02T09:20:59-06:00

GiteaMirror commented

2025-11-02 09:20:59 -06:00

Originally created by @wxiaoguang on GitHub (May 20, 2023).

Feature Description

Gitea's path system was not well designed, it just got patched and patched and accumulated a lot of problems:

The root problem is, Gitea tries to guess these paths, and the environment/command argument/config option affect each other.

This a a refactoring plan for improving this system and resolving the problem with minimal breaking.

Deprecate the environment GITEA_XXX_DIR and command argument "--custom-dir / --work-dir"
When "gitea web" runs, try to detect whether there is an absolute "WORK_DIR" in app.ini
- If no, use "guessed" absolute WorkDir to update the config
Other commands always use the "WORK_DIR" in app.ini

There could be more details, I think this plan is feasible and stable.

Screenshots

No response

Originally created by @wxiaoguang on GitHub (May 20, 2023). ### Feature Description Gitea's path system was not well designed, it just got patched and patched and accumulated a lot of problems: * #21498 * #24222 * #17846 * #21606 * #25107 The root problem is, Gitea tries to guess these paths, and the environment/command argument/config option affect each other. This a a refactoring plan for improving this system and resolving the problem with minimal breaking. 1. Deprecate the environment GITEA_XXX_DIR and command argument "--custom-dir / --work-dir" 2. When "gitea web" runs, try to detect whether there is an absolute "WORK_DIR" in app.ini * If no, use "guessed" absolute WorkDir to update the config 3. Other commands always use the "WORK_DIR" in app.ini There could be more details, I think this plan is feasible and stable. ### Screenshots _No response_

GiteaMirror added the type/proposal type/feature labels 2025-11-02 09:20:59 -06:00

GiteaMirror closed this issue

2025-11-02 09:20:59 -06:00

GiteaMirror commented

2025-11-02 09:21:00 -06:00

@silverwind commented on GitHub (May 20, 2023):

Generally agree. If there is no WORK_DIR in config, default it to current working directory. I would not write back into config at all. Writing into config should be avoided wherever possible.

@silverwind commented on GitHub (May 20, 2023): Generally agree. If there is no `WORK_DIR` in config, default it to current working directory. I would not write back into config at all. Writing into config should be avoided wherever possible.

GiteaMirror commented

2025-11-02 09:21:01 -06:00

@wxiaoguang commented on GitHub (May 20, 2023):

default it to current working directory.

It doesn't work. The "writing back" is necessary.

eg: some people do this:

put gitea in /usr/loca/bin
the "working dir" is /data/gitea
use GITEA_WORK_DIR to run gitea web
when run other commands, other commands only have --config option.

@wxiaoguang commented on GitHub (May 20, 2023): > default it to current working directory. It doesn't work. The "writing back" is necessary. eg: some people do this: * put `gitea` in `/usr/loca/bin` * the "working dir" is `/data/gitea` * use GITEA_WORK_DIR to run `gitea web` * when run other commands, other commands only have `--config` option.

GiteaMirror commented

2025-11-02 09:21:01 -06:00

@eeyrjmr commented on GitHub (May 20, 2023):

thing is, an application shouldn't write to /etc so if gitea needs to store such persistent changes it really should go into $HOME/.config/gitea.ini (or /var/lib/gitea/*) but this just adds more confusion as to where a setting is actually being set, as well as a full backup and restore

@eeyrjmr commented on GitHub (May 20, 2023): thing is, an application shouldn't write to /etc so if gitea needs to store such persistent changes it really should go into $HOME/.config/gitea.ini (or /var/lib/gitea/*) but this just adds more confusion as to where a setting is actually being set, as well as a full backup and restore

GiteaMirror commented

2025-11-02 09:21:01 -06:00

@silverwind commented on GitHub (May 20, 2023):

GITEA_WORK_DIR

This variable is mislabeled. A working directory in the classic sense is the directory where the application runs in. Not necessarily the directory where the data resides. A better name would be GITEA_DATA_DIR where subdirectories like repos exist, but I guess we can only change so much while staying compatible.

@silverwind commented on GitHub (May 20, 2023): > * GITEA_WORK_DIR This variable is mislabeled. A working directory in the classic sense is the directory where the application runs in. Not necessarily the directory where the data resides. A better name would be `GITEA_DATA_DIR` where subdirectories like `repos` exist, but I guess we can only change so much while staying compatible.

GiteaMirror commented

2025-11-02 09:21:01 -06:00

@wxiaoguang commented on GitHub (May 20, 2023):

thing is, an application shouldn't write to /etc so if gitea needs to store such persistent changes it really should go into $HOME/.config/gitea.ini (or /var/lib/gitea/*) but this just adds more confusion as to where a setting is actually being set, as well as a full backup and restore

If the app.ini is read-only, Gitea will prompt users to manually set the WORK_DIR correctly in their config file.

@wxiaoguang commented on GitHub (May 20, 2023): > thing is, an application shouldn't write to /etc so if gitea needs to store such persistent changes it really should go into $HOME/.config/gitea.ini (or /var/lib/gitea/*) but this just adds more confusion as to where a setting is actually being set, as well as a full backup and restore If the `app.ini` is read-only, Gitea will prompt users to manually set the WORK_DIR correctly in their config file.

GiteaMirror commented

2025-11-02 09:21:01 -06:00

@wxiaoguang commented on GitHub (May 20, 2023):

GITEA_WORK_DIR

This variable is mislabeled. A working directory in the classic sense is the directory where the application runs in. Not necessarily the directory where the data resides. A better name would be GITEA_DATA_DIR where subdirectories like repos exist, but I guess we can only change so much while staying compatible.

There was already a DataDir in code.

In history, the code only got patched and patched (as an open-source project, I can understand), no design, refactoring or improvement, so the situation becomes today's problems.

@wxiaoguang commented on GitHub (May 20, 2023): > > * GITEA_WORK_DIR > > This variable is mislabeled. A working directory in the classic sense is the directory where the application runs in. Not necessarily the directory where the data resides. A better name would be `GITEA_DATA_DIR` where subdirectories like `repos` exist, but I guess we can only change so much while staying compatible. There was already a `DataDir` in code. In history, the code only got patched and patched (as an open-source project, I can understand), no design, refactoring or improvement, so the situation becomes today's problems.

GiteaMirror commented

2025-11-02 09:21:01 -06:00

@eeyrjmr commented on GitHub (May 20, 2023):

thing is, an application shouldn't write to /etc so if gitea needs to store such persistent changes it really should go into $HOME/.config/gitea.ini (or /var/lib/gitea/*) but this just adds more confusion as to where a setting is actually being set, as well as a full backup and restore

If the app.ini is read-only, Gitea will prompt users to manually set the WORK_DIR correctly in their config file.

I appreciate that but for a correctly configured system /etc shouldn't be writable by non-root and if it was writeable by non-root implies a system that has some serious issue if it is compromised.
with gitea not being launchable as root, it is extremely safe to assume that /etc would not be writable.

So if it can be assumed that /etc isn't writable by root and gitea would not run as root, where would such settings be storable by gitea?

database
$WORK_DIR
$XDG_CONFIG_HOME

@eeyrjmr commented on GitHub (May 20, 2023): > > thing is, an application shouldn't write to /etc so if gitea needs to store such persistent changes it really should go into $HOME/.config/gitea.ini (or /var/lib/gitea/*) but this just adds more confusion as to where a setting is actually being set, as well as a full backup and restore > > If the `app.ini` is read-only, Gitea will prompt users to manually set the WORK_DIR correctly in their config file. I appreciate that but for a correctly configured system /etc shouldn't be writable by non-root and if it was writeable by non-root implies a system that has some serious issue if it is compromised. with gitea not being launchable as root, it is extremely safe to assume that /etc would not be writable. So if it can be assumed that /etc isn't writable by root and gitea would not run as root, where would such settings be storable by gitea? 1. database 2. $WORK_DIR 3. $XDG_CONFIG_HOME

GiteaMirror commented

2025-11-02 09:21:01 -06:00

@wxiaoguang commented on GitHub (May 20, 2023):

where would such settings be storable by gitea?

Sorry I don't get the point. The whole picture in my mind is:

For a fresh installation:

No config/data on disk
Run gitea web
Visit the "install" page, set "work dir"
Gitea save the config into "work dir/custom/app.ini"
Then gitea could run with "--config work-dir/custom/app.ini"

For an existing installation (upgrading):

Stop old gitea
Run gitea web
Gitea tries to write the GITEA_WORK_DIR into "app.ini"
- If the "app.ini" is read-only, let site admin manually set this value
Then gitea could run with "--config app.ini"

(there could be some slightly different cases, IMO all of them could be covered)

Does this answer your question? Or could you help to show some bad cases?

@wxiaoguang commented on GitHub (May 20, 2023): > where would such settings be storable by gitea? Sorry I don't get the point. The whole picture in my mind is: For a fresh installation: 1. No config/data on disk 2. Run `gitea web` 3. Visit the "install" page, set "work dir" 4. Gitea save the config into "work dir/custom/app.ini" 5. Then gitea could run with "--config work-dir/custom/app.ini" For an existing installation (upgrading): 1. Stop old gitea 2. Run `gitea web` 3. Gitea tries to write the GITEA_WORK_DIR into "app.ini" * If the "app.ini" is read-only, let site admin manually set this value 4. Then gitea could run with "--config app.ini" (there could be some slightly different cases, IMO all of them could be covered) ---- Does this answer your question? Or could you help to show some bad cases?

GiteaMirror commented

2025-11-02 09:21:02 -06:00

@eeyrjmr commented on GitHub (May 20, 2023):

my bad, I interpreted aspects of this as advocating writing to /etc/gitea/app.ini

@eeyrjmr commented on GitHub (May 20, 2023): my bad, I interpreted aspects of this as advocating writing to /etc/gitea/app.ini

GiteaMirror commented

2025-11-02 09:21:02 -06:00

@lunny commented on GitHub (May 20, 2023):

Maybe we should introduce another file to store the write-back information including tokens.

@lunny commented on GitHub (May 20, 2023): Maybe we should introduce another file to store the write-back information including tokens.

GiteaMirror commented

2025-11-02 09:21:02 -06:00

@silverwind commented on GitHub (May 22, 2023):

It's not completely unheard of that applications write back into config, Redis does it too. But I agree, a second file would be good where we could write stuff to, e.g. app.override.ini or something.

@silverwind commented on GitHub (May 22, 2023): It's not completely unheard of that applications write back into config, Redis does it too. But I agree, a second file would be good where we could write stuff to, e.g. `app.override.ini` or something.

Sign in to join this conversation.

Branches Tags

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: github-starred/gitea#10879