foster/forgejo-docs
0
0
Fork 0
mirror of https://codeberg.org/forgejo/docs.git synced 2024-11-28 18:42:51 -05:00
Code Issues Activity

Reverse Proxy setup guide (#600)

Browse source 
I've added a more comprehensive guide to set up Reverse Proxies.

So far I've added nginx configuration, I'm also planning to add apache configuration later on.

Reviewed-on: https://codeberg.org/forgejo/docs/pulls/600
Reviewed-by: Earl Warren <earl-warren@noreply.codeberg.org>
Co-authored-by: Kwonunn <kwonunnx@gmail.com>
Co-committed-by: Kwonunn <kwonunnx@gmail.com>
(cherry picked from commit c1b7969c1d)
This commit is contained in:
Kwonunn 2024-05-10 07:22:19 +00:00 committed by github-actions[bot]
parent adec18c29d
commit 4db9cb08cd
1 changed files with 194 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

194
docs/admin/reverse-proxy.md
View file

@ -4,6 +4,200 @@ license: 'Apache-2.0'
origin_url: 'https://github.com/go-gitea/gitea/blob/e865de1e9d65dc09797d165a51c8e705d2a86030/docs/content/usage/authentication.en-us.md'
---
You may wish to place your Forgejo instance behind a reverse proxy. A reverse proxy is a server that accepts requests from the outside and routes them to internal services, like Forgejo.
## nginx
### Basic HTTP
To set up a basic HTTP reverse proxy in nginx, create a file `forgejo.conf` in `/etc/nginx/conf.d` and add the following configuration:
```conf
server {
listen 80; # Listen on IPv4 port 80
listen [::]:80; # Listen on IPv6 port 80
server_name git.example.com; # Change this to the server domain name.
location / {
proxy_pass http://127.0.0.1:3000; # Port 3000 is the default Forgejo port
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;
client_max_body_size 512M;
}
}
```
Make sure to reload/restart nginx after chaning the configuration.
### HTTP with a subpath
If you want to serve Forgejo on a subpath, e.g. on `http://example.com/forgejo`, use the following configuration:
```conf
server {
listen 80; # Listen on IPv4 port 80
listen [::]:80; # Listen on IPv6 port 80
server_name git.example.com; # Change this to the server domain name.
location /forgejo/ { # Replace forgejo here with your subpath
rewrite ^ $request_uri;
rewrite ^/forgejo(/.*) $1 break;
return 400;
proxy_pass http://127.0.0.1:3000$uri;
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;
client_max_body_size 512M;
}
}
```
Make sure to set the Forgejo `ROOT_URL` configuration key to the URL _with_ the subpath, otherwise links generated by Forgejo will be broken.
### HTTPS
When using a reverse proxy, it's usually easier to let the proxy handle HTTPS. It's easy to set up HTTPS on nginx.
#### HTTPS with Certbot
To set up HTTPS with Certbot, first set up an HTTP reverse proxy with the configuration above and ensure that it works as expected. To use HTTPS you need to have a domain name.
Then, install [certbot](https://certbot.eff.org/). When running certbot, select the domain name that your Forgejo instance is hosted under, and choose automatic installation. This should automatically set up HTTPS on port 443 and a redirect on the old port 80.
You may wish to change the `ROOT_URL` configuration key to the HTTPS protocol so links generated by Forgejo automatically use HTTPS.
#### HTTPS with manually installed certificates
If you have obtained certificates from elsewhere or have chosen not to let certbot automatically install them, make the following changes to the configuration file:
**Change the listening ports**
Change the lines
```conf
listen 80;
listen [::]:80;
```
to
```conf
listen 443 ssl http2;
listen [::]:443 ssl http2;
```
**Add the SSL certificate information**
Generate an SSL configuration at [mozilla](https://ssl-config.mozilla.org/#server=nginx), and add the SSL parameters to your configuration file. Make sure to replace the paths in the example with paths to your certificate files.
**Add a redirect from HTTP**
Outside the server block, add this redirection block:
```conf
server {
listen 80 default_server;
listen [::]:80 default_server;
location / {
return 301 https://$host$request_uri;
}
}
```
This will redirect anyone visiting the HTTP site to the HTTPS site.
## Apache
### Basic HTTP
To set up a basic HTTP proxy in Apache, create a file `100-forgejo.conf` in `/etc/apache2/sites-available` and add the following configuration:
```xml
<VirtualHost *:80>
ServerName git.example.com
ProxyPreserveHost On
ProxyRequests off
AllowEncodedSlashes NoDecode
ProxyPass / http://127.0.0.1:3000/ nocanon
</VirtualHost>
```
Next, enable the site with `a2ensite 100-forgejo.conf` and enable the proxy modules with `a2enmod proxy proxy_http`. Finally, restart the apache server.
### HTTP with a subpath
If you want to serve Forgejo on a subpath, e.g. on `http://example.com/forgejo`, use the following configuration:
```xml
<VirtualHost *:80>
ServerName git.example.com
ProxyPreserveHost On
ProxyRequests off
AllowEncodedSlashes NoDecode
ProxyPass /forgejo http://127.0.0.1:3000/ nocanon # Change /forgejo here to your desired subpath.
</VirtualHost>
```
Make sure to set the Forgejo `ROOT_URL` configuration key to the URL _with_ the subpath, otherwise links generated by Forgejo will be broken.
### HTTPS
When using a reverse proxy, it's usually easier to let the proxy handle HTTPS. It's easy to set up HTTPS on apache.
#### HTTPS with Certbot
To set up HTTPS with Certbot, first set up an HTTP reverse proxy with the configuration above and ensure that it works as expected. To use HTTPS you need to have a domain name.
Then, install [certbot](https://certbot.eff.org/). When running certbot, select the domain name that your Forgejo instance is hosted under, and choose automatic installation. This should automatically set up HTTPS on port 443 and a redirect on the old port 80.
You may wish to change the `ROOT_URL` configuration key to the HTTPS protocol so links generated by Forgejo automatically use HTTPS.
#### HTTPS with manually installed certificates
If you have obtained certificates from elsewhere or have chosen not to let certbot automatically install them, make the following changes to the configuration file:
**Change the listening ports**
Change `<VirtualHost *:80>` to `<VirtualHost *:443>`.
**Add the SSL certificate information**
Generate an SSL configuration at [mozilla](https://ssl-config.mozilla.org/#server=apache), and add the SSL parameters to your configuration file. Make sure to replace the paths in the example with paths to your certificate files.
**Add a redirect from HTTP**
Outside the `VirtualHost *:443`, add this configuration:
```conf
<VirtualHost *:80>
ServerName git.example.com
RewriteEngine on
RewriteCond %{SERVER_NAME} =git.example.com
RewriteRule ^ https://%{SERVER_NAME}%{REQUEST_URI} [END,NE,R=permanent]
</VirtualHost>
```
This will redirect anyone visiting the HTTP site to the HTTPS site.
## Proxy Authentication
Forgejo supports Reverse Proxy Header authentication, it will read headers as a trusted login user name or user email address. This hasn't been enabled by default, you can enable it with
```ini