Multi-domain support, ROOT_URL problem, use relative URLs in templates instead of absolute URLs #8799

New Issue

GiteaMirror · 2025-11-02T08:18:44-06:00

GiteaMirror commented

2025-11-02 08:18:44 -06:00

Originally created by @wxiaoguang on GitHub (Apr 8, 2022).

At the moment, Gitea users must set ROOT_URL correctly in app.ini, otherwise many URLs on the web UI will be wrong, which makes the web UI doesn't work properly (CSRF tokens and cookies can not work across domains)

The ROOT_URL must be set to the full URL which the users visit, with correct scheme(eg: https://the-gitea-domain/) and correct sub path if it is used (eg: https://the-gitea-domain/my-gitea-path/).

New code should always use relative URLs for Web UI.

Many maintainers have answered the issues about incorrect ROOT_URL again and again.

Using HTMLURL(and other absolute URLs) in templates is the root case that Gitea can only serve web under ROOT_URL.

That's why we have to force users to set ROOT_URL correctly.

If all URLs in template can be refactored to use Relative URL correctly, then we do not need to force users set ROOT_URL correctly again and again.

The ROOT_URL is still needed because for example, some webhooks need the absolute URL for external systems, and Gitea should show absolute URL on the UI for clone link, etc.

#20436 , after installation, Gitea may redirect user to an incorrect location.
#20089 , it may resolve the incorrect redirection problem during installation.

The PR to detect the problem:

https://github.com/go-gitea/gitea/pull/18971

Originally created by @wxiaoguang on GitHub (Apr 8, 2022). **At the moment, Gitea users must set ROOT_URL correctly in `app.ini`, otherwise many URLs on the web UI will be wrong, which makes the web UI doesn't work properly (CSRF tokens and cookies can not work across domains)** The ROOT_URL must be set to the full URL which the users visit, with correct scheme(eg: `https://the-gitea-domain/`) and correct sub path if it is used (eg: `https://the-gitea-domain/my-gitea-path/`). New code should always use relative URLs for Web UI. ---- Many maintainers have answered the issues about incorrect ROOT_URL again and again. Using `HTMLURL`(and other absolute URLs) in templates is the root case that Gitea can only serve web under ROOT_URL. That's why we have to force users to set ROOT_URL correctly. If all URLs in template can be refactored to use Relative URL correctly, then we do not need to force users set ROOT_URL correctly again and again. The ROOT_URL is still needed because for example, some webhooks need the absolute URL for external systems, and Gitea should show absolute URL on the UI for clone link, etc. Related: * https://github.com/go-gitea/gitea/issues/14254 * https://github.com/go-gitea/gitea/issues/17912 * https://github.com/go-gitea/gitea/issues/17843 * https://github.com/go-gitea/gitea/issues/19340 * https://github.com/go-gitea/gitea/issues/19963 * https://github.com/go-gitea/gitea/issues/6397 (5 up-votes!) * https://github.com/go-gitea/gitea/issues/8697 (19 up-votes!) * https://github.com/go-gitea/gitea/issues/20091 * https://github.com/go-gitea/gitea/issues/20450 Some more related: * #20436 , after installation, Gitea may redirect user to an incorrect location. * #20089 , it may resolve the incorrect redirection problem during installation. The PR to detect the problem: * https://github.com/go-gitea/gitea/pull/18971

GiteaMirror added the topic/ui type/proposal issue/confirmed type/refactoring labels 2025-11-02 08:18:44 -06:00

GiteaMirror closed this issue

2025-11-02 08:18:44 -06:00

GiteaMirror commented

2025-11-02 08:18:46 -06:00

@silverwind commented on GitHub (Apr 8, 2022):

+1, relative URLs may even enable use cases like running on multiple domains. Thought IIRC, ROOT_URL still needs to stay in the config because sometimes absolute URLs need to be built, like for PR link when pushing via SSH. But it's good nonetheless to remove dependencies on ROOT_URL where possible.

@silverwind commented on GitHub (Apr 8, 2022): +1, relative URLs may even enable use cases like running on multiple domains. Thought IIRC, ROOT_URL still needs to stay in the config because sometimes absolute URLs need to be built, like for PR link when pushing via SSH. But it's good nonetheless to remove dependencies on ROOT_URL where possible.

GiteaMirror commented

2025-11-02 08:18:47 -06:00

@lunny commented on GitHub (Apr 8, 2022):

We need a new global variable ROOT_URL_PATH, it could be / or sub path like /gitea. For repository, we could have a new HTMLURLPath

@lunny commented on GitHub (Apr 8, 2022): We need a new global variable `ROOT_URL_PATH`, it could be `/` or sub path like `/gitea`. For repository, we could have a new `HTMLURLPath`

GiteaMirror commented

2025-11-02 08:18:47 -06:00

@silverwind commented on GitHub (Jul 22, 2022):

As seen in https://github.com/go-gitea/gitea/issues/20450, dashboard repo links are one example of incorrect absolute URLs.

@silverwind commented on GitHub (Jul 22, 2022): As seen in https://github.com/go-gitea/gitea/issues/20450, dashboard repo links are one example of incorrect absolute URLs.

GiteaMirror commented

2025-11-02 08:18:47 -06:00

@k6Q28k5w5eWuRuuzTg9j7GrKCbjt7 commented on GitHub (Aug 14, 2022):

First time I have tried gitea and find it surprising that there is no mention of this at all on the docs. The docs give an impression that the user can set the environment, but this is incorrect. I'll give a subset of examples, there are several more:

Documentation: Install with docker
To bind the integrated OpenSSH daemon and the webserver on a different port, adjust the port section. It’s common to just change the host port and **keep the ports within the container like they are**.

Gitea explicitly overrides a lot of headers and links. The advice to differentiate the environment e.g. inside and outside a container, only makes sense if the application offers the configuration feature. E.g. docker mapping to port 3000, instead of 80 or 443, will make you really wonder what the source of the fault is then links dont work. At least by mimic'ing the env on standard ports, some subset will resolve properly.

Documentation: Managing deployments with environemt variables
In addition to the environment variables above, **any settings in app.ini can be set or overridden with an environment variable** of the form: GITEA__SECTION_NAME__KEY_NAME.

This is pure misinformation as the application never properly supported configuration in this manner. The docs seems to be describing a roadmap of how it should end up to be, rather than the factual.

Documentation: Recommended server configuration
NOTE: Many of the following directories can be configured using [Environment Variables](https://docs.gitea.io/en-us/environment-variables/) as well! Of note, configuring GITEA_WORK_DIR will tell Gitea where to base its working directory, as well as ease installation.

and

Documentation: reverse proxies

No, the application will override the proxy headers e.g. all of the repository links. This will break your env if you rely on the proxy with redirects URI also.

If you follow the docs you will end up with a broken system going in a loop until you find the source of the problem. Would it be possible to mention that this doesnt work on the docs? :)

@k6Q28k5w5eWuRuuzTg9j7GrKCbjt7 commented on GitHub (Aug 14, 2022): First time I have tried gitea and find it surprising that there is no mention of this at all on the docs. The docs give an impression that the user can set the environment, but this is incorrect. I'll give a subset of examples, there are several more: [Documentation: Install with docker](https://docs.gitea.io/en-us/install-with-docker/#ports) `To bind the integrated OpenSSH daemon and the webserver on a different port, adjust the port section. It’s common to just change the host port and **keep the ports within the container like they are**.` Gitea explicitly overrides a lot of headers and links. The advice to _differentiate_ the environment e.g. inside and outside a container, only makes sense if the application offers the configuration feature. E.g. docker mapping to port 3000, instead of 80 or 443, will make you really wonder what the source of the fault is then links dont work. At least by mimic'ing the env on standard ports, some subset will resolve properly. [Documentation: Managing deployments with environemt variables](https://docs.gitea.io/en-us/install-with-docker/#managing-deployments-with-environment-variables) `In addition to the environment variables above, **any settings in app.ini can be set or overridden with an environment variable** of the form: GITEA__SECTION_NAME__KEY_NAME.` This is pure misinformation as the application never properly supported configuration in this manner. The docs seems to be describing a roadmap of how it should end up to be, rather than the factual. [Documentation: **Recommended** server configuration](https://docs.gitea.io/en-us/install-from-binary/#recommended-server-configuration) `NOTE: Many of the following directories can be configured using [Environment Variables](https://docs.gitea.io/en-us/environment-variables/) as well! Of note, configuring GITEA_WORK_DIR will tell Gitea where to base its working directory, as well as ease installation.` and [Documentation: reverse proxies](https://docs.gitea.io/en-us/reverse-proxies/#nginx) No, the application will override the proxy headers e.g. all of the repository links. This will break your env if you rely on the proxy with redirects URI also. If you follow the docs you will end up with a broken system going in a loop until you find the source of the problem. Would it be possible to mention that this doesnt work on the docs? :)

GiteaMirror commented

2025-11-02 08:18:48 -06:00

@nwmcsween commented on GitHub (Aug 25, 2022):

So what is the fix here? Refactor HTMLURL to return relative URLS and punt explicit absolute URLS to new config options like SSH? This seems to be an epic but all issues except one (but I think more is needed than JS here) is left open.

@nwmcsween commented on GitHub (Aug 25, 2022): So what is the fix here? Refactor HTMLURL to return relative URLS and punt explicit absolute URLS to new config options like SSH? This seems to be an epic but all issues except one (but I think more is needed than JS here) is left open.

GiteaMirror commented

2025-11-02 08:18:49 -06:00

@lunny commented on GitHub (Sep 19, 2022):

So I think we need an ALLOWED_ROOT_URLS, which could have a glob matching. When a request to a disallowed root url, Gitea should return 404 or redirect to 404.

I found it's difficult to get the right root url in the backend because maybe there are some reverse proxies. So it's only done by frontend.

But ROOT_URL cannot be removed because some places need that. i.e. When sending an email, the link needs an absolute url. We can reuse ROOT_URL as the default value of that.

@lunny commented on GitHub (Sep 19, 2022): So I think we need an `ALLOWED_ROOT_URLS`, which could have a glob matching. When a request to a disallowed root url, Gitea should return 404 or redirect to 404. I found it's difficult to get the right root url in the backend because maybe there are some reverse proxies. So it's only done by frontend. But `ROOT_URL` cannot be removed because some places need that. i.e. When sending an email, the link needs an absolute url. We can reuse `ROOT_URL` as the default value of that.

GiteaMirror commented

2025-11-02 08:18:49 -06:00

@wxiaoguang commented on GitHub (Sep 19, 2022):

I do not think so. No more option is needed. I do not agree with "when a request to a disallowed root url, Gitea should return 404 or redirect to 404.": it's not related to this problem, and it's never a real problem.

The proper solution is to refactor most HTMLURLs in templates to relative URLs.

And the global ROOT_URL is necessary and must, see the origin comment:

The ROOT_URL is still needed because for example, some webhooks need the absolute URL for external systems, and Gitea should show absolute URL on the UI for clone link, etc.

@wxiaoguang commented on GitHub (Sep 19, 2022): I do not think so. No more option is needed. I do not agree with "when a request to a disallowed root url, Gitea should return 404 or redirect to 404.": it's not related to this problem, and it's never a real problem. The proper solution is to refactor most HTMLURLs in templates to relative URLs. And the global ROOT_URL is necessary and must, see the origin comment: > The ROOT_URL is still needed because for example, some webhooks need the absolute URL for external systems, and Gitea should show absolute URL on the UI for clone link, etc.

GiteaMirror commented

2025-11-02 08:18:50 -06:00

@wxiaoguang commented on GitHub (Sep 19, 2022):

To explain why "mismatched ROOT_URL makes the web UI doesn't work properly": because the CSRF tokens and cookies can not work across origin. Users will be affected by: be redirected to a non-login site, fail to do ajax requests, fail to submit forms, etc. (I updated the origin comment)

I had a full plan about how to do the refactoring, but doing refactoring for Gitea is pretty difficult. Unless there are enough maintainers promising to support this refactoring, I do not have confidence to work on it.

@wxiaoguang commented on GitHub (Sep 19, 2022): To explain why "mismatched ROOT_URL makes the web UI doesn't work properly": because the CSRF tokens and cookies can not work across origin. Users will be affected by: be redirected to a non-login site, fail to do ajax requests, fail to submit forms, etc. (I updated the origin comment) I had a full plan about how to do the refactoring, but doing refactoring for Gitea is pretty difficult. Unless there are enough maintainers promising to support this refactoring, I do not have confidence to work on it.

GiteaMirror commented

2025-11-02 08:18:50 -06:00

@defkev commented on GitHub (Sep 30, 2022):

I just hit this warning after upgrading an instance to 1.17 (from 1.15?) with ROOT_URL set to its FQDN (e.g. http://git.domain.local:3000/)

Now most users on this network get a DNS-suffix (e.g. domain.local) provided by DHCP who access the frontend using just the hostname (http://git:3000) for convenience who now get the warning about the supposedly "wrong" ROOT_URL:

Your ROOT_URL in app.ini is http://git.domain.local:3000/ but you are visiting http://git:3000/
You should set ROOT_URL correctly, otherwise the web may not work correctly.

Which doesn't make a whole lot of sense to begin with:
a ) The network-stack will always resolve the hostname to its FQDN using the provided DNS-suffix so this doesn't affect CSRF
b) This should probably not be checked on the client-site (using e.g. window.location)

Now, as a workaround, i could pipe gitea through a reverse proxy to redirect git to git.domain.local pointing A to the reverse proxy to get rid of the warning but this would ultimately break ssh unless i also add an ssh proxy.

So either ignore the warning in this scenario (option in app.ini?) or add the redirect to the build in webserver shipping with gitea as this is only affecting the web part anyway.

Cheers

@defkev commented on GitHub (Sep 30, 2022): I just hit this warning after upgrading an instance to 1.17 (from 1.15?) with ROOT_URL set to its FQDN (e.g. http://git.domain.local:3000/) Now most users on this network get a DNS-suffix (e.g. domain.local) provided by DHCP who access the frontend using just the hostname (http://git:3000) for convenience who now get the warning about the supposedly "wrong" ROOT_URL: >Your ROOT_URL in app.ini is http://git.domain.local:3000/ but you are visiting http://git:3000/ >You should set ROOT_URL correctly, otherwise the web may not work correctly. Which doesn't make a whole lot of sense to begin with: a ) The network-stack will always resolve the hostname to its FQDN using the provided DNS-suffix so this doesn't affect CSRF b) This should probably not be checked on the client-site (using e.g. window.location) Now, as a workaround, i could pipe gitea through a reverse proxy to redirect git to git.domain.local pointing A to the reverse proxy to get rid of the warning but this would ultimately break ssh unless i also add an ssh proxy. So either ignore the warning in this scenario (option in app.ini?) or add the redirect to the build in webserver shipping with gitea as this is only affecting the web part anyway. Cheers

GiteaMirror commented

2025-11-02 08:18:51 -06:00

@wxiaoguang commented on GitHub (Sep 30, 2022):

If you are sure you can ignore the warning, there is a bypass method to hide the warning, see the FAQ in #18971 .

There is a specialized CSS class "js-global-error" for the error message, then end users still have a chance to hide these error messages by customized CSS styles.

edited: ⚠️ please see the WARNING in other comments, do not do so ⚠️

@wxiaoguang commented on GitHub (Sep 30, 2022): If you are sure you can ignore the warning, there is a bypass method to hide the warning, see the FAQ in #18971 . > There is a specialized CSS class "js-global-error" for the error message, then end users still have a chance to hide these error messages by customized CSS styles. ---- edited: ⚠️ please see the WARNING in other comments, do not do so ⚠️

GiteaMirror commented

2025-11-02 08:18:51 -06:00

@defkev commented on GitHub (Sep 30, 2022):

Thank you very much, i found the PR after posting the comment.

$CustomPath/public/css/header.css:

.js-global-error {
    display: none !important;
}

$CustomPath/templates/custom/header.tmpl:

<link rel="stylesheet" href="/assets/css/header.css">

Hacky but it works 😁

edited by wxiaoguang: ⚠️ please see the WARNING in other comments, do not do so ⚠️

@defkev commented on GitHub (Sep 30, 2022): Thank you very much, i found the PR after posting the comment. <details> `$CustomPath/public/css/header.css`: ``` .js-global-error { display: none !important; } ``` `$CustomPath/templates/custom/header.tmpl`: ``` <link rel="stylesheet" href="/assets/css/header.css"> ``` Hacky but it works :grin: </details> ---- edited by wxiaoguang: ⚠️ please see the WARNING in other comments, do not do so ⚠️

GiteaMirror commented

2025-11-02 08:18:52 -06:00

@ddddavid-he commented on GitHub (Sep 30, 2022):

Thank you very much, i found the PR after posting the comment.

.js-global-error.....

this is a wonderfully nice solution

edited by wxiaoguang: please see the WARNING in other comments, do not do so.

@ddddavid-he commented on GitHub (Sep 30, 2022): > Thank you very much, i found the PR after posting the comment. > > `.js-global-error.....` > this is a wonderfully nice solution ---- edited by wxiaoguang: please see the WARNING in other comments, do not do so.

GiteaMirror commented

2025-11-02 08:18:52 -06:00

@wxiaoguang commented on GitHub (Oct 1, 2022):

⚠️ WARNING about ignoring the "inconsistent domain" message

To be clear : if you see the error message but you ignore it, you will run into problem.

Please DO NOT do so before Gitea has a clear solution, unless that you are very very sure about what you are doing and you can resolve all your users' problems. That's why I didn't make an option or provide any detail steps for hiding it.

I will hide some unrelated comments and edit to put some warnings in some comments, because if many users ignore the warning, there will be a lot of duplicate issues here reporting that "something doesn't work" (it happened before).

For example, user who log in https://git/ can not do preview if the ROOT_URL is https://git.domain/. They can not do inline PR comment either, there could be more similar problems. You can only ignore the error message if you are sure your users won't use these affected features on different domains.

@wxiaoguang commented on GitHub (Oct 1, 2022): ### ⚠️ WARNING about ignoring the "inconsistent domain" message To be clear : if you see the error message but you ignore it, you will run into problem. Please DO NOT do so before Gitea has a clear solution, unless that you are very very sure about what you are doing and you can resolve all your users' problems. That's why I didn't make an option or provide any detail steps for hiding it. I will hide some unrelated comments and edit to put some warnings in some comments, because if many users ignore the warning, there will be a lot of duplicate issues here reporting that "something doesn't work" (it happened before). For example, user who log in `https://git/` can not do preview if the ROOT_URL is `https://git.domain/`. They can not do inline PR comment either, there could be more similar problems. You can only ignore the error message if you are sure your users won't use these affected features on different domains. ![image](https://user-images.githubusercontent.com/2114189/193375573-31df483e-3ec0-42d7-a8f8-488cffc9e7eb.png)

GiteaMirror commented

2025-11-02 08:18:52 -06:00

@ddddavid-he commented on GitHub (Oct 1, 2022):

Got it. Thanks for your very kind notice.

@ddddavid-he commented on GitHub (Oct 1, 2022): Got it. Thanks for your very kind notice.

GiteaMirror commented

2025-11-02 08:18:53 -06:00

@badiku commented on GitHub (Nov 7, 2022):

hi, how to force bind to only one domain name?

e.g. allow http://localhost but disable directly access by ip: http://127.0.0.1

if the ROOT_URL is https://git.domain/. how to forbid other users to visit it by https://git/ , if they both point to same IP address?

@badiku commented on GitHub (Nov 7, 2022): hi, how to force bind to only one domain name? e.g. allow http://localhost but disable directly access by ip: http://127.0.0.1 if the ROOT_URL is https://git.domain/. how to forbid other users to visit it by https://git/ , if they both point to same IP address?

GiteaMirror commented

2025-11-02 08:18:53 -06:00

@lunny commented on GitHub (Nov 7, 2022):

hi, how to force bind to only one domain name?

e.g. allow http://localhost but disable directly access by ip: http://127.0.0.1

if the ROOT_URL is https://git.domain/. how to forbid other users to visit it by https://git/ , if they both point to same IP address?

You can do that in reverseproxy.

@lunny commented on GitHub (Nov 7, 2022): > hi, how to force bind to only one domain name? > > e.g. allow http://localhost but disable directly access by ip: http://127.0.0.1 > > if the ROOT_URL is https://git.domain/. how to forbid other users to visit it by https://git/ , if they both point to same IP address? You can do that in reverseproxy.

GiteaMirror commented

2025-11-02 08:18:54 -06:00

@badiku commented on GitHub (Nov 7, 2022):

thank you .

I want to achieve this without another proxy service like nginx.

there's a setting Http_addr to bind IP, but not for bind host.

maybe I can modify template .tmpl page file to display blank page if detected ip

@badiku commented on GitHub (Nov 7, 2022): thank you . I want to achieve this without another proxy service like nginx. there's a setting Http_addr to bind IP, but not for bind host. maybe I can modify template .tmpl page file to display blank page if detected ip

GiteaMirror commented

2025-11-02 08:18:55 -06:00

@scubbo commented on GitHub (Jan 4, 2023):

Another possibly-related issue here - I'm trying to set up my instance so that it's accessible independently in two ways:

via gitea.local, where DNS resolution happens directly on my router and no external Internet access is required
via gitea.my-domain-name.org, where DNS resolution and request routing happen via the wider Internet

AFAICT, that's not possible for Docker registry operations since the response to docker login references settings.APPUrl which is derived from ROOT_URL - that is, an attempt to docker login to gitea.local will fail.

@scubbo commented on GitHub (Jan 4, 2023): Another possibly-related issue [here](https://github.com/go-gitea/gitea/issues/22033) - I'm trying to set up my instance so that it's accessible independently in two ways: * via `gitea.local`, where DNS resolution happens directly on my router and no external Internet access is required * via `gitea.my-domain-name.org`, where DNS resolution and request routing happen via the wider Internet AFAICT, that's not possible for Docker registry operations since the response to `docker login` references `settings.APPUrl` which is derived from `ROOT_URL` - that is, an attempt to `docker login` to `gitea.local` will fail.

GiteaMirror commented

2025-11-02 08:18:55 -06:00

@jolheiser commented on GitHub (Feb 6, 2023):

Re-opening as linked PR only partially resolved this issue

@jolheiser commented on GitHub (Feb 6, 2023): Re-opening as linked PR only partially resolved this issue

GiteaMirror commented

2025-11-02 08:18:56 -06:00

@wxiaoguang commented on GitHub (Feb 7, 2023):

Most problems in this issue have been addressed by #21986, so I think it's good to:

Remove most ROOT_URL error messages on the page, only show it to site admin.
Close this issue
Open a new issue to follow remaining and new problems.

Now the "Multidomain support" is about 50%-70%.

A correct main domain (ROOT_URL) is still necessary, because Gitea sends mails/notifications with no knowledge of "current domain"
There are still incorrect usages of AppURL(ROOT_URL) in code, which should be cleaned one by one in the future.

@wxiaoguang commented on GitHub (Feb 7, 2023): Most problems in this issue have been addressed by #21986, so I think it's good to: 1. Remove most ROOT_URL error messages on the page, only show it to site admin. 2. Close this issue 3. Open a new issue to follow remaining and new problems. ---- Now the "Multidomain support" is about 50%-70%. * A correct main domain (ROOT_URL) is still necessary, because Gitea sends mails/notifications with no knowledge of "current domain" * There are still incorrect usages of AppURL(ROOT_URL) in code, which should be cleaned one by one in the future.

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