Gitea's path system quirk and bug

[wxiaoguang]

Description

In history, Gitea's binary was designed to use the binary directory as working directory, it tries to create/use its "data"/"custom" directories in the binary path. For example: running /usr/local/bin/gitea makes Gitea try to use /usr/local/bin/custom directory, which is improper/wrong, and it causes a lot of problems.

POSIX users please use https://github.com/go-gitea/gitea/tree/main/contrib/fhs-compliant-script , do not put Gitea binary into /usr/loca/bin directory -- unless you are 100% sure about the details.

"custom" bug

• GITEA_WORK_DIR not being used for GITEA_CUSTOM when looking up locales #21498

A feedback from discord

---

Update gitea from 1.15.6 to 1.15.7 (and then 1.19.1):

Failed to include custom: open /usr/local/bin/custom/conf/app.ini: permission denied
2023/04/20 06:06:09 cmd/dump.go:150:fatal() [F] Failed to include custom: open /usr/local/bin/custom/conf/app.ini: permission denied

I'm using the script in contrib/upgrade.sh and as far as I'm concerned I have never used this "custom" folder, why is it needed? (I am using sqlite3 as well)

I don't get why it's trying to read/write in that particular folder and not from /var/lib/gitea/custom

[aru]

I was able to solve this issue by just adding the proper backupopts:

 giteauser=gitea backupopts="-c /etc/gitea/app.ini -C /var/lib/gitea/custom" ./gitea_upgrade.sh -v 1.15.7

[zeripath]

It's difficult to come up with a reasonable way to improve what's going on without understanding why things are the way they are.

I've said this before, but for the sake of completeness I'll say it again.

---

Gitea was initially intended to be run from the directory it was built in or a directory similar to it and NOT from /usr/bin/gitea.

It would use the directory of its binary as the basis for where it would look for its assets and where it would create its data.

Over time, options and configuration were added to allow this directories to be changed from these defaults but ... fundamentally the paths are all built up in a hierarchical fashion from the work-path - that is, the absolute path of the Gitea binary.

Now... changing that is difficult without causing lots of breakage.

---

1. I believe that it is important that Gitea should just run from the directory that you compile it in.
2. Similarly Gitea should continue to be able to be run from any directory that it is run in.
3. However, the current situation is not ideal because people want to be able to dump Gitea in /usr/local/bin and /usr/bin and to have it just work.

We have been bodging 3 for a while by providing the script to wrap Gitea in a filesystem hierarchy compliant way and we can compile Gitea with paths in-built to avoid having dependencies on the work-path.

Our Dockers finally wrap Gitea in the FHS script which means that these problems should no longer occur in the docker.

Our documentation used to advise people to wrap Gitea in the FHS script instead of placing it in /usr/bin but clearly someone thought that was too complicated and has removed it. Unsurprisingly this will have caused problems to resurface.

---

Now... We have several options (for this particular problem):

1. Go back to advising people to wrap Gitea in the script or to compile it properly with the paths built-in. HOWEVER this is yet another ill-considered documentation simplification PR away from being broken.
2. Make Gitea search for its configuration in some standard places depending on where it is started.

The search path in 2 could depend on the directory that Gitea finds itself in or it could just be common depending on how gitea was started.

---

The linked issue (#23301) is related but it's also likely related to incomplete configuration - in this case there should be a conf.ini but there is still an important path (APP_DATA_PATH) that is incompletely defined and so is dependent on the APP_WORK_PATH. A breaking option for dealing with this is to assert that the conf.ini must contain the absolute path to the data directory, this would be very breaking indeed as far as I can see.

---

So to reiterate, Gitea is the way it is because it was never intended to be placed in /usr/bin or /usr/local/bin.

The documentation USED to advise the use of the wrapper script for such placement.

We should add this back in to the documentation. I can't understand why this was ever removed.

I think we should consider a search path approach to finding the configuration if -c is not provided. We can add a warning if there is any dependency on --work-path.

[jolheiser]

I don't recall which docs referenced the FHS script, and a cursory search wouldn't tell me when it existed or was removed.

The install from binary docs mention setting the correct env vars, but I don't recall it ever mentioning the FHS script. (Although it may be worth adding)
The systemd page also points to the example service, which also sets those env vars.

Do you recall where it was at? I agree with adding it somewhere, it would potentially save us some bug reports. I'm just curious to the reasoning to remove it.

[DanielGibson]

Three things that might make all this less painful:

1. Let gitea (esp. doctor --fix) ignore if the custom directory doesn't exist and/or can't be created (after all, using it is optional and only needed if you want to modify gitea's data like html templates or whatever) - unless the user explicitly specifies that they want to use a custom directory (or use the embedded command to extract the resources to a custom directory
2. Allow specifying AppWorkPath and CustomPath (and maybe more?) in app.ini, so the user only needs to set the CustomConf path instead of all the others as well when calling gitea on the commandline
3. Search for app.ini in some more directories (if it wasn't found in one try the next). For example, on Linux (or generally Unix-likes) it could try to use /etc/gitea/app.ini if $CustomPath/conf/app.ini doesn't exist, and maybe if that doesn't exist try $HOME/.config/gitea/app.ini or something like that? (or maybe first try the path in $HOME and then in /etc/)

I think all these changes could be implemented in a backwards-compatible way.

[DanielGibson]

If the AppWorkPath was stored in the app.ini, blobless clones would work in systemwide installations, see https://codeberg.org/forgejo/forgejo/issues/869
(I haven't tested this with Gitea, but would be surprised if it behaved any differently, unless you recently fixed this bug)

[DanielGibson]

I just tested forgejo 1.20rc0, and it looks like the working_path/data is now stored in the app.ini (under [server] APP_DATA_PATH) and that is used by forgejo serve --config /path/to/app.ini .... so the aforementioned issue seems fixed now - cool! :)

Did you also happen to introduce an environment variable to set the path to the app.ini?
Then users wouldn't have to specify that for every command, either :)

[wxiaoguang]

I don't understand forgejo.

Gitea's related code hasn't been changed for long time, APP_DATA_PATH is always stored in app.ini, from very long time ago

And, if it is not absolute path, there should already be a log message to remind users (since 1.17)

[DanielGibson]

Gitea's related code hasn't been changed for long time, APP_DATA_PATH is always stored in app.ini, from very long time ago

Nope, I just tested gitea 1.19.3, same as in forgejo 1.19.3.
I downloaded the binary to /tmp/, then did:

$ cd /tmp/
$ chmod 755 gitea-1.19.3-linux-amd64
$ mkdir -p /tmp/gitea_work_dir/etc
$ ./gitea-1.19.3-linux-amd64 -w /tmp/gitea_work_dir -c /tmp/gitea_work_dir/etc/app.ini

Then I opened http://localhost:3000/ in a webbrowser and did the initial installation/configuration step.
Here's the app.ini that was generated - as you can see, it doesn't contain an APP_DATA_PATH line.

And here's the output I got in the console: gitea-output.txt
I don't see any warnings about APP_DATA_PATH there.

[wxiaoguang]

I see, there is something wrong with #19815

[DanielGibson]

I see, there is something wrong with #19815

No, why? The path I passed to gitea is absolute, it's just not saved in the app.ini (at least as APP_DATA_PATH, it is set correctly as part of database.PATH, repository.ROOT, lfs.PATH, etc)

[wxiaoguang]

#19815 introduced another patch for APP_DATA_PATH, but it forgot to write the correct APP_DATA_PATH when installing.

If there was no such patch but a complete refactoring, then I think there won't be such bug.

---

Update: Write absolute AppDataPath to app.ini when installing #25331 is still not ideal