Prompt user on installation for intended usage #14674

New Issue

GiteaMirror · 2025-11-02T11:19:41-06:00

GiteaMirror commented

2025-11-02 11:19:41 -06:00

Originally created by @delvh on GitHub (Jun 28, 2025).

Feature Description

At the moment, there are a couple of modes of using Gitea, depending on your use case.
Most often, the use cases boil down to one of the following (did I forget any?):

Small instance for a couple of known users, low-end hardware
Slightly larger instance for a couple more of known users, better hardware
Public instance
Larger company with strict rules

Additionally, there are typically the following network modes:

Gitea has free internet access
Gitea is located inside an intranet to allow only access inside a company

These modes of usage often conflict with each other in terms of expectations for what Gitea should offer - i.e. larger organizations need orgs, teams, and being able to assign an issue to multiple projects, public instances need everything and especially user limits, small instances have typically little use for advanced features like teams or limits, …

Historically, we often enough had the problem that a feature was developed with one specific group in mind, while the others at best ignore this feature or actively suffer from it (having to manually disable it or worse).

As such, I can only see one problem going forward to make the experience more seemless:
Prompting the user when installing exactly how the instance is expected to be used.
Existing instances should fail to start if these two config options (use case and network restrictiveness) haven't been set.

Depending on the chosen usage mode, config option default values can be chosen dynamically.

This proposal explicitly does not propose any explicit config default value changes.
Such a discussion should only take place once this proposal has been implemented.

Thoughts?

Originally created by @delvh on GitHub (Jun 28, 2025). ### Feature Description At the moment, there are a couple of modes of using Gitea, depending on your use case. Most often, the use cases boil down to one of the following (did I forget any?): - Small instance for a couple of known users, low-end hardware - Slightly larger instance for a couple more of known users, better hardware - Public instance - Larger company with strict rules Additionally, there are typically the following network modes: - Gitea has free internet access - Gitea is located inside an intranet to allow only access inside a company These modes of usage often conflict with each other in terms of expectations for what Gitea should offer - i.e. larger organizations need orgs, teams, and being able to assign an issue to multiple projects, public instances need everything and especially user limits, small instances have typically little use for advanced features like teams or limits, … Historically, we often enough had the problem that a feature was developed with one specific group in mind, while the others at best ignore this feature or actively suffer from it (having to manually disable it or worse). As such, I can only see one problem going forward to make the experience more seemless: Prompting the user when installing exactly how the instance is expected to be used. Existing instances should fail to start if these two config options (use case and network restrictiveness) haven't been set. Depending on the chosen usage mode, config option default values can be chosen dynamically. This proposal explicitly does not propose any explicit config default value changes. Such a discussion should only take place once this proposal has been implemented. Thoughts?

GiteaMirror added the type/proposal label 2025-11-02 11:19:41 -06:00

GiteaMirror commented

2025-11-02 11:19:41 -06:00

@TheFox0x7 commented on GitHub (Jun 29, 2025):

Wouldn't it make more sense to provide this in docs? Sort of a combination of premade settings and HW requirements for such deployment?

I'm a bit worried that this would add another layer to settings before we fix issues we have there now like old keys which still work despite being removed, lack of ability to split config into subfiles and similar.

But overall it's not a bad idea.

@TheFox0x7 commented on GitHub (Jun 29, 2025): Wouldn't it make more sense to provide this in docs? Sort of a combination of premade settings and HW requirements for such deployment? I'm a bit worried that this would add another layer to settings before we fix issues we have there now like old keys which still work despite being removed, lack of ability to split config into subfiles and similar. But overall it's not a bad idea.

GiteaMirror commented

2025-11-02 11:19:41 -06:00

@delvh commented on GitHub (Jun 29, 2025):

You first need to find these docs while installing your instance.
That in itself should not be the biggest problem and is most likely feasible to expect from someone setting up an instance.
The only problem might arise if you follow an outdated third-party tutorial (i.e. someone's blog or similar).
What I meant was that the usage only decides the default value of some config options (i.e. [actions].DEFAULT_ACTIONS_URL would be set to self by default when Gitea is deployed within an internal network, but to github in all other cases). If you manually set the config option, your manually configured value takes precedence. In other words, it is supposed to simplify configuring Gitea.
I think I understand what you mean by additional layer, but I don't think it would affect the situation with still accepting old keys since we don't use the default value in this case but the manually configured value. On the contrary, it would rather ensure that your config is updated automatically when upgrading - in two ways:
Firstly, it updates values automatically if they change.
Secondly, it might reduce the number of options you need to configure. That would help to prevent this "still accepting old keys" problem since if you don't declare them, you don't rely on them and thus don't need the old key to be present.
I see it as a minimal maintenance burden on the project for the benefit that more stuff will just work out of the box.

So, overall, I see this proposal as putting more emphasis on the painless aspect of

Gitea is a painless, self-hosted, all-in-one software development service

@delvh commented on GitHub (Jun 29, 2025): 1. You first need to find these docs while installing your instance. That in itself should not be the biggest problem and is most likely feasible to expect from someone setting up an instance. The only problem might arise if you follow an outdated third-party tutorial (i.e. someone's blog or similar). 2. What I meant was that the usage only decides the **default value** of some config options (i.e. `[actions].DEFAULT_ACTIONS_URL` would be set to `self` by default when Gitea is deployed within an internal network, but to `github` in all other cases). If you manually set the config option, your manually configured value takes precedence. In other words, it is supposed to simplify configuring Gitea. 3. I think I understand what you mean by additional layer, but I don't think it would affect the situation with still accepting old keys since we don't use the default value in this case but the manually configured value. On the contrary, it would rather ensure that your config is updated automatically when upgrading - in two ways: Firstly, it updates values automatically if they change. Secondly, it might reduce the number of options you need to configure. That would help to prevent this "still accepting old keys" problem since if you don't declare them, you don't rely on them and thus don't need the old key to be present. I see it as a minimal maintenance burden on the project for the benefit that more stuff will just _work_ out of the box. So, overall, I see this proposal as putting more emphasis on the `painless` aspect of > Gitea is a painless, self-hosted, all-in-one software development service

GiteaMirror commented

2025-11-02 11:19:42 -06:00

@wxiaoguang commented on GitHub (Jun 30, 2025):

I agree that we can improve the "install page", to make it easier and better for most users, make default config choices based on their usage.

IMO it is more like a "research & design" task at the beginning stage.

@wxiaoguang commented on GitHub (Jun 30, 2025): I agree that we can improve the "install page", to make it easier and better for most users, make default config choices based on their usage. IMO it is more like a "research & design" task at the beginning stage.

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#14674