Lunny Xiao
106a813e08
Five documentation fixes that do not depend on anything upstream. **PostgreSQL version in the docker guide** (closes #224) The compose example pinned `postgres:14`, the oldest version Gitea still tests against, and PostgreSQL does not upgrade its data directory on its own, so every new deployment that copies the example is one major upgrade behind from day one. The example now uses `postgres:18`, with a note about why the major version is pinned and a pointer to the supported range. **SELinux** (closes #211) `setcap 'cap_net_bind_service=+ep'` is what the docs suggest for binding to a port below 1024, but it is denied under SELinux depending on the label of the binary, and it is lost on every upgrade because the capability lives in an extended attribute of the file. A new page describes granting the capability through the systemd unit instead (`AmbientCapabilities`, plus `PrivateUsers=false` when the sandboxing gets in the way), the `semanage fcontext` / `restorecon` labels for the binary and the data directory, and how to read the denials with `ausearch` and `audit2allow`. It is linked from the binary and source installation pages and from the `gitea web` notes. **OAuth2 and OpenID Connect** (closes #106) The authentication page documented LDAP, PAM, SMTP, FreeIPA, SPNEGO and the reverse proxy, but not that Gitea can log users in against an external OAuth2 or OpenID Connect provider, which made it look like the only OAuth2 support is Gitea acting as the provider. The new section covers the fields of the authentication source, the callback URL to register at the provider, the group and claim mappings, and the `[oauth2_client]` settings, and separates it from the older OpenID 2.0 sign-in. **IIS reverse proxy** (closes #39) Application Request Routing rewrites the host of the `Location` header back to the internal one while "Reverse rewrite host in response headers" is on, which sends the browser to `127.0.0.1:3000` after a sign-in. The IIS section now says to turn it off and where the setting lives. **ACME in containers** (closes #292) `ACME_DIRECTORY` defaults to the relative path `https`, which is resolved against the working directory of the process. In the official image that is `/app/gitea`, outside the `/data` volume, so a recreated container asks the CA for a new certificate and runs into the Let's Encrypt limit of 5 certificates per week for the same domains. The HTTPS page now warns about it and shows an absolute path inside the volume; the cheat sheet entry points at the warning. The default itself is being changed in https://github.com/go-gitea/gitea/pull/35851, the note stays useful for every released version. Only `docs/` is touched, the released versions keep their content. <!-- cloudflare-preview --> Preview: https://pr-513.docs-gitea-com.pages.dev Reviewed-on: https://gitea.com/gitea/docs/pulls/513 Reviewed-by: bircni <[email protected]> Co-authored-by: Lunny Xiao <[email protected]>
5.6 KiB
date, slug, sidebar_position, aliases
| date | slug | sidebar_position | aliases | |
|---|---|---|---|---|
| 2018-06-02T11:00:00+02:00 | https-setup | 12 |
|
HTTPS Setup
Using the built-in server
Before you enable HTTPS, make sure that you have valid SSL/TLS certificates.
You could use self-generated certificates for evaluation and testing. Please run gitea cert --host [HOST] to generate a self signed certificate.
If you are using Apache or nginx on the server, it's recommended to check the reverse proxy guide.
To use Gitea's built-in HTTPS support, you must change your app.ini file:
[server]
PROTOCOL = https
ROOT_URL = https://git.example.com:3000/
HTTP_PORT = 3000
CERT_FILE = cert.pem
KEY_FILE = key.pem
Note that if your certificate is signed by a third party certificate authority (i.e. not self-signed), then cert.pem should contain the certificate chain. The server certificate must be the first entry in cert.pem, followed by the intermediaries in order (if any). The root certificate does not have to be included because the connecting client must already have it in order to establish the trust relationship. To learn more about the config values, please checkout the Config Cheat Sheet.
For the CERT_FILE or KEY_FILE field, the file path is relative to the GITEA_CUSTOM environment variable when it is a relative path. It can be an absolute path as well.
Setting up HTTP redirection
The Gitea server is only able to listen to one port; to redirect HTTP requests to the HTTPS port, you will need to enable the HTTP redirection service:
[server]
REDIRECT_OTHER_PORT = true
; Port the redirection service should listen on
PORT_TO_REDIRECT = 3080
If you are using Docker, make sure that this port is configured in your docker-compose.yml file.
Using ACME (Default: Let's Encrypt)
ACME is a Certificate Authority standard protocol that allows you to automatically request and renew SSL/TLS certificates. Let's Encrypt is a free publicly trusted Certificate Authority server using this standard. Only HTTP-01 and TLS-ALPN-01 challenges are implemented. In order for ACME challenges to pass and verify your domain ownership, external traffic to the gitea domain on port 80 (HTTP-01) or port 443 (TLS-ALPN-01) has to be served by the gitea instance. Setting up HTTP redirection and port-forwards might be needed for external traffic to route correctly. Normal traffic to port 80 will otherwise be automatically redirected to HTTPS. You must consent to the ACME provider's terms of service (default Let's Encrypt's terms of service).
Minimum setup using the default Let's Encrypt:
[server]
PROTOCOL=https
DOMAIN=git.example.com
ENABLE_ACME=true
ACME_ACCEPTTOS=true
ACME_DIRECTORY=https
;; Email can be omitted here and provided manually at first run, after which it is cached
ACME_EMAIL=[email protected]
Minimum setup using a smallstep CA, refer to their tutorial for more information.
[server]
PROTOCOL=https
DOMAIN=git.example.com
ENABLE_ACME=true
ACME_ACCEPTTOS=true
ACME_URL=https://ca.example.com/acme/acme/directory
;; Can be omitted if using the system's trust is preferred
;ACME_CA_ROOT=/path/to/root_ca.crt
ACME_DIRECTORY=https
ACME_EMAIL=[email protected]
To learn more about the config values, please checkout the Config Cheat Sheet.
:::warning
ACME_DIRECTORY is where the account key and the issued certificates are
cached, and the default https is a relative path, resolved against the working
directory of the Gitea process. In the official Docker image that working
directory is /app/gitea, which is part of the container and not of the /data
volume, so every recreated container starts without an account and without
certificates and asks the CA for new ones. Let's Encrypt allows
5 certificates per week for the
same set of domains, after which the instance is left without a working
certificate until the limit expires.
Point the setting at a path inside the volume when running in a container:
[server]
ACME_DIRECTORY=/data/gitea/https
The rootless image keeps its working directory (/var/lib/gitea) in a volume,
so it is only affected when that volume is not persisted.
:::
Using a reverse proxy
Setup up your reverse proxy as shown in the reverse proxy guide.
After that, enable HTTPS by following one of these guides:
:::note Enabling HTTPS only at the proxy level is referred as TLS Termination Proxy. The proxy server accepts incoming TLS connections, decrypts the contents, and passes the now unencrypted contents to Gitea. This is normally fine as long as both the proxy and Gitea instances are either on the same machine, or on different machines within private network (with the proxy is exposed to outside network). If your Gitea instance is separated from your proxy over a public network, or if you want full end-to-end encryption, you can also enable HTTPS support directly in Gitea using built-in server and forward the connections over HTTPS instead. :::