# Reverse Proxies
+## General configuration
+
+1. Set `[server] ROOT_URL = https://git.example.com/` in your `app.ini` file.
+2. Make the reverse-proxy pass `https://git.example.com/foo` to `http://gitea:3000/foo`.
+3. Make sure the reverse-proxy does not decode the URI. The request `https://git.example.com/a%2Fb` should be passed as `http://gitea:3000/a%2Fb`.
+4. Make sure `Host` and `X-Fowarded-Proto` headers are correctly passed to Gitea to make Gitea see the real URL being visited.
+
+### Use a sub-path
+
+Usually it's **not recommended** to put Gitea in a sub-path, it's not widely used and may have some issues in rare cases.
+
+To make Gitea work with a sub-path (eg: `https://common.example.com/gitea/`),
+there are some extra requirements besides the general configuration above:
+
+1. Use `[server] ROOT_URL = https://common.example.com/gitea/` in your `app.ini` file.
+2. Make the reverse-proxy pass `https://common.example.com/gitea/foo` to `http://gitea:3000/foo`.
+3. The container registry requires a fixed sub-path `/v2` at the root level which must be configured:
+ - Make the reverse-proxy pass `https://common.example.com/v2` to `http://gitea:3000/v2`.
+ - Make sure the URI and headers are also correctly passed (see the general configuration above).
+
## Nginx
-If you want Nginx to serve your Gitea instance, add the following `server` section to the `http` section of `nginx.conf`:
+If you want Nginx to serve your Gitea instance, add the following `server` section to the `http` section of `nginx.conf`.
-```
-server {
- listen 80;
- server_name git.example.com;
+Make sure `client_max_body_size` is large enough, otherwise there would be "413 Request Entity Too Large" error when uploading large files.
+```nginx
+server {
+ ...
location / {
client_max_body_size 512M;
proxy_pass http://localhost:3000;
}
```
-### Resolving Error: 413 Request Entity Too Large
-
-This error indicates nginx is configured to restrict the file upload size,
-it affects attachment uploading, form posting, package uploading and LFS pushing, etc.
-You can fine tune the `client_max_body_size` option according to [nginx document](http://nginx.org/en/docs/http/ngx_http_core_module.html#client_max_body_size).
-
## Nginx with a sub-path
-In case you already have a site, and you want Gitea to share the domain name, you can setup Nginx to serve Gitea under a sub-path by adding the following `server` section inside the `http` section of `nginx.conf`:
+In case you already have a site, and you want Gitea to share the domain name,
+you can setup Nginx to serve Gitea under a sub-path by adding the following `server` section
+into the `http` section of `nginx.conf`:
-```
+```nginx
server {
- listen 80;
- server_name git.example.com;
-
- # Note: Trailing slash
- location /gitea/ {
+ ...
+ location ~ ^/(gitea|v2)($|/) {
client_max_body_size 512M;
- # make nginx use unescaped URI, keep "%2F" as is
+ # make nginx use unescaped URI, keep "%2F" as-is, remove the "/gitea" sub-path prefix, pass "/v2" as-is.
rewrite ^ $request_uri;
- rewrite ^/gitea(/.*) $1 break;
+ rewrite ^(/gitea)?(/.*) $2 break;
proxy_pass http://127.0.0.1:3000$uri;
# other common HTTP headers, see the "Nginx" config section above
- proxy_set_header ...
+ proxy_set_header Connection $http_connection;
+ proxy_set_header Upgrade $http_upgrade;
+ proxy_set_header Host $host;
+ proxy_set_header X-Real-IP $remote_addr;
+ proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+ proxy_set_header X-Forwarded-Proto $scheme;
}
}
```
-Then you **MUST** set something like `[server] ROOT_URL = http://git.example.com/git/` correctly in your configuration.
+Then you **MUST** set something like `[server] ROOT_URL = http://git.example.com/gitea/` correctly in your configuration.
## Nginx and serve static resources directly
Set `[server] STATIC_URL_PREFIX = /_/static` in your configuration.
-```apacheconf
+```nginx
server {
listen 80;
server_name git.example.com;
Set `[server] STATIC_URL_PREFIX = http://cdn.example.com/gitea` in your configuration.
-```apacheconf
+```nginx
# application server running Gitea
server {
listen 80;
}
```
-```apacheconf
+```nginx
# static content delivery server
server {
listen 80;
ProxyRequests off
AllowEncodedSlashes NoDecode
ProxyPass / http://localhost:3000/ nocanon
+ ProxyPreserveHost On
+ RequestHeader set "X-Forwarded-Proto" expr=%{REQUEST_SCHEME}
</VirtualHost>
```
AllowEncodedSlashes NoDecode
# Note: no trailing slash after either /git or port
ProxyPass /git http://localhost:3000 nocanon
+ ProxyPreserveHost On
+ RequestHeader set "X-Forwarded-Proto" expr=%{REQUEST_SCHEME}
</VirtualHost>
```
If you want Caddy to serve your Gitea instance, you can add the following server block to your Caddyfile:
-```apacheconf
+```
git.example.com {
reverse_proxy localhost:3000
}
In case you already have a site, and you want Gitea to share the domain name, you can setup Caddy to serve Gitea under a sub-path by adding the following to your server block in your Caddyfile:
-```apacheconf
+```
git.example.com {
route /git/* {
uri strip_prefix /git
This config assumes that you are handling HTTPS on the traefik side and using HTTP between Gitea and traefik.
Then you **MUST** set something like `[server] ROOT_URL = http://example.com/gitea/` correctly in your configuration.
-
-## General sub-path configuration
-
-Usually it's not recommended to put Gitea in a sub-path, it's not widely used and may have some issues in rare cases.
-
-If you really need to do so, to make Gitea works with sub-path (eg: `http://example.com/gitea/`), here are the requirements:
-
-1. Set `[server] ROOT_URL = http://example.com/gitea/` in your `app.ini` file.
-2. Make the reverse-proxy pass `http://example.com/gitea/foo` to `http://gitea-server:3000/foo`.
-3. Make sure the reverse-proxy not decode the URI, the request `http://example.com/gitea/a%2Fb` should be passed as `http://gitea-server:3000/a%2Fb`.
-
-## Docker / Container Registry
-
-The container registry uses a fixed sub-path `/v2` which can't be changed.
-Even if you deploy Gitea with a different sub-path, `/v2` will be used by the `docker` client.
-Therefore you may need to add an additional route to your reverse proxy configuration.
return err == nil && urlIsRelative(s, u)
}
-func guessRequestScheme(req *http.Request, def string) string {
+func getRequestScheme(req *http.Request) string {
// https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-Proto
if s := req.Header.Get("X-Forwarded-Proto"); s != "" {
return s
if s := req.Header.Get("X-Forwarded-Ssl"); s != "" {
return util.Iif(s == "on", "https", "http")
}
- return def
+ return ""
}
-func guessForwardedHost(req *http.Request) string {
+func getForwardedHost(req *http.Request) string {
// https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-Host
return req.Header.Get("X-Forwarded-Host")
}
if !ok {
return setting.AppURL
}
- if host := guessForwardedHost(req); host != "" {
- // if it is behind a reverse proxy, use "https" as default scheme in case the site admin forgets to set the correct forwarded-protocol headers
- return guessRequestScheme(req, "https") + "://" + host + setting.AppSubURL + "/"
- } else if req.Host != "" {
- // if it is not behind a reverse proxy, use the scheme from config options, meanwhile use "https" as much as possible
- defaultScheme := util.Iif(setting.Protocol == "http", "http", "https")
- return guessRequestScheme(req, defaultScheme) + "://" + req.Host + setting.AppSubURL + "/"
+ // If no scheme provided by reverse proxy, then do not guess the AppURL, use the configured one.
+ // At the moment, if site admin doesn't configure the proxy headers correctly, then Gitea would guess wrong.
+ // There are some cases:
+ // 1. The reverse proxy is configured correctly, it passes "X-Forwarded-Proto/Host" headers. Perfect, Gitea can handle it correctly.
+ // 2. The reverse proxy is not configured correctly, doesn't pass "X-Forwarded-Proto/Host" headers, eg: only one "proxy_pass http://gitea:3000" in Nginx.
+ // 3. There is no reverse proxy.
+ // Without an extra config option, Gitea is impossible to distinguish between case 2 and case 3,
+ // then case 2 would result in wrong guess like guessed AppURL becomes "http://gitea:3000/", which is not accessible by end users.
+ // So in the future maybe it should introduce a new config option, to let site admin decide how to guess the AppURL.
+ reqScheme := getRequestScheme(req)
+ if reqScheme == "" {
+ return setting.AppURL
+ }
+ reqHost := getForwardedHost(req)
+ if reqHost == "" {
+ reqHost = req.Host
}
- return setting.AppURL
+ return reqScheme + "://" + reqHost + setting.AppSubURL + "/"
}
func MakeAbsoluteURL(ctx context.Context, s string) string {
func TestMakeAbsoluteURL(t *testing.T) {
defer test.MockVariableValue(&setting.Protocol, "http")()
- defer test.MockVariableValue(&setting.AppURL, "http://the-host/sub/")()
+ defer test.MockVariableValue(&setting.AppURL, "http://cfg-host/sub/")()
defer test.MockVariableValue(&setting.AppSubURL, "/sub")()
ctx := context.Background()
- assert.Equal(t, "http://the-host/sub/", MakeAbsoluteURL(ctx, ""))
- assert.Equal(t, "http://the-host/sub/foo", MakeAbsoluteURL(ctx, "foo"))
- assert.Equal(t, "http://the-host/sub/foo", MakeAbsoluteURL(ctx, "/foo"))
+ assert.Equal(t, "http://cfg-host/sub/", MakeAbsoluteURL(ctx, ""))
+ assert.Equal(t, "http://cfg-host/sub/foo", MakeAbsoluteURL(ctx, "foo"))
+ assert.Equal(t, "http://cfg-host/sub/foo", MakeAbsoluteURL(ctx, "/foo"))
assert.Equal(t, "http://other/foo", MakeAbsoluteURL(ctx, "http://other/foo"))
ctx = context.WithValue(ctx, RequestContextKey, &http.Request{
Host: "user-host",
})
- assert.Equal(t, "http://user-host/sub/foo", MakeAbsoluteURL(ctx, "/foo"))
+ assert.Equal(t, "http://cfg-host/sub/foo", MakeAbsoluteURL(ctx, "/foo"))
ctx = context.WithValue(ctx, RequestContextKey, &http.Request{
Host: "user-host",
"X-Forwarded-Host": {"forwarded-host"},
},
})
- assert.Equal(t, "https://forwarded-host/sub/foo", MakeAbsoluteURL(ctx, "/foo"))
+ assert.Equal(t, "http://cfg-host/sub/foo", MakeAbsoluteURL(ctx, "/foo"))
ctx = context.WithValue(ctx, RequestContextKey, &http.Request{
Host: "user-host",
}
func apiUnauthorizedError(ctx *context.Context) {
+ // TODO: it doesn't seem quite right but it doesn't really cause problem at the moment.
+ // container registry requires that the "/v2" must be in the root, so the sub-path in AppURL should be removed, ideally.
ctx.Resp.Header().Add("WWW-Authenticate", `Bearer realm="`+httplib.GuessCurrentAppURL(ctx)+`v2/token",service="container_registry",scope="*"`)
apiErrorDefined(ctx, errUnauthorized)
}
err := json.Unmarshal(resp.Body.Bytes(), &data)
assert.NoError(t, err)
assert.Equal(t, []string{
- ctx.Locale.TrString("admin.self_check.location_origin_mismatch", "http://frontend/sub/", "http://host/sub/"),
+ ctx.Locale.TrString("admin.self_check.location_origin_mismatch", "http://frontend/sub/", "http://config/sub/"),
}, data.Problems)
}
projects / gitea.git / commitdiff