Improve documentation for PAM and static deployment (#21866)

## Changes proposed in [referenced issue 21845][1]

- Expand PAM configuration description with working examples.
- Clarify `STATIC_URL_PREFIX` use (include "assets" and only works after
database has been initialized)
- Add note for HTTPS proxy support VIA Apache.

[1]: https://github.com/go-gitea/gitea/issues/21845
This commit is contained in:
Andrew Buettner 2022-11-20 14:14:03 -06:00 committed by GitHub
parent 32db62515f
commit 43aafc5ba1
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
2 changed files with 46 additions and 5 deletions

View file

@ -289,8 +289,13 @@ The following configuration set `Content-Type: application/vnd.android.package-a
This includes CSS files, images, JS files and web fonts.
Avatar images are dynamic resources and still served by Gitea.
The option can be just a different path, as in `/static`, or another domain, as in `https://cdn.example.com`.
Requests are then made as `%(ROOT_URL)s/static/css/index.css` and `https://cdn.example.com/css/index.css` respective.
Requests are then made as `%(ROOT_URL)s/static/assets/css/index.css` or `https://cdn.example.com/assets/css/index.css` respectively.
The static files are located in the `public/` directory of the Gitea source repository.
You can proxy the STATIC_URL_PREFIX requests to Gitea server to serve the static
assets, or copy the manually built Gitea assets from `$GITEA_BUILD/public` to
the assets location, eg: `/var/www/assets`, make sure `$STATIC_URL_PREFIX/assets/css/index.css`
points to `/var/www/assets/css/index.css`.
- `HTTP_ADDR`: **0.0.0.0**: HTTP listen address.
- If `PROTOCOL` is set to `fcgi`, Gitea will listen for FastCGI requests on TCP socket
defined by `HTTP_ADDR` and `HTTP_PORT` configuration settings.

View file

@ -166,11 +166,47 @@ Uses the following fields:
## PAM (Pluggable Authentication Module)
To configure PAM, set the 'PAM Service Name' to a filename in `/etc/pam.d/`. To
work with normal Linux passwords, the user running Gitea must have read access
to `/etc/shadow`.
This procedure enables PAM authentication. Users may still be added to the
system manually using the user administration. PAM provides a mechanism to
automatically add users to the current database by testing them against PAM
authentication. To work with normal Linux passwords, the user running Gitea
must also have read access to `/etc/shadow` in order to check the validity of
the account when logging in using a public key.
**Note**: PAM support is added via [build-time flags](https://docs.gitea.io/en-us/install-from-source/#build), and the official binaries provided do not have this enabled.
**Note**: If a user has added SSH public keys into Gitea, the use of these
keys _may_ bypass the login check system. Therefore, if you wish to disable a user who
authenticates with PAM, you _should_ also manually disable the account in Gitea using the
built-in user manager.
1. Configure and prepare the installation.
- It is recommended that you create an administrative user.
- Deselecting automatic sign-up may also be desired.
1. Once the database has been initialized, log in as the newly created
administrative user.
1. Navigate to the user setting (icon in top-right corner), and select
`Site Administration` -> `Authentication Sources`, and select
`Add Authentication Source`.
1. Fill out the field as follows:
- `Authentication Type` : `PAM`
- `Name` : Any value should be valid here, use "System Authentication" if
you'd like.
- `PAM Service Name` : Select the appropriate file listed under `/etc/pam.d/`
that performs the authentication desired.[^1]
- `PAM Email Domain` : The e-mail suffix to append to user authentication.
For example, if the login system expects a user called `gituser`, and this
field is set to `mail.com`, then Gitea will expect the `user email` field
for an authenticated GIT instance to be `gituser@mail.com`.[^2]
**Note**: PAM support is added via [build-time flags](https://docs.gitea.io/en-us/install-from-source/#build),
and the official binaries provided do not have this enabled. PAM requires that
the necessary libpam dynamic library be available and the necessary PAM
development headers be accessible to the compiler.
[^1]: For example, using standard Linux log-in on Debian "Bullseye" use
`common-session-noninteractive` - this value may be valid for other flavors of
Debian including Ubuntu and Mint, consult your distribution's documentation.
[^2]: **This is a required field for PAM**. Be aware: In the above example, the
user will log into the Gitea web interface as `gituser` and not `gituser@mail.com`
## SMTP (Simple Mail Transfer Protocol)