From 59378257dca2acf7a85d0580698e66743641bf8a Mon Sep 17 00:00:00 2001 From: Andrew Buettner Date: Fri, 18 Nov 2022 20:20:35 -0500 Subject: [PATCH 1/3] Documentation changes: Changes proposed in [referenced issue 21845](https://github.com/go-gitea/gitea/issues/21845) --- .../doc/advanced/config-cheat-sheet.en-us.md | 16 ++++++- .../doc/features/authentication.en-us.md | 46 +++++++++++++++++-- .../doc/usage/reverse-proxies.en-us.md | 2 +- 3 files changed, 57 insertions(+), 7 deletions(-) diff --git a/docs/content/doc/advanced/config-cheat-sheet.en-us.md b/docs/content/doc/advanced/config-cheat-sheet.en-us.md index aece6afc08020..08847a64a6f32 100644 --- a/docs/content/doc/advanced/config-cheat-sheet.en-us.md +++ b/docs/content/doc/advanced/config-cheat-sheet.en-us.md @@ -289,8 +289,18 @@ 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/asset/css/index.css` and `https://cdn.example.com/asset/css/index.css` respective. The static files are located in the `public/` directory of the Gitea source repository. + Copy this directory to the `/static` location eg: `/var/www/static` and rename + it to `assets` eg:[^1] + +```bash +cd /var/www +mkdir static +cp -a $GITEA_BUILD/public static +mv static/public static/assets +``` + - `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. @@ -406,6 +416,10 @@ The following configuration set `Content-Type: application/vnd.android.package-a - `GRACEFUL_HAMMER_TIME`: **60s**: After a restart the parent process will stop accepting new connections and will allow requests to finish before stopping. Shutdown will be forced if it takes longer than this time. - `STARTUP_TIMEOUT`: **0**: Shutsdown the server if startup takes longer than the provided time. On Windows setting this sends a waithint to the SVC host to tell the SVC host startup may take some time. Please note startup is determined by the opening of the listeners - HTTP/HTTPS/SSH. Indexers may take longer to startup and can have their own timeouts. +[^1]: Gitea's initial configuration form will not work correctly with +`STATIC_URL_PREFIX` enabled. Use this option only after successfully deploying +Gitea and initializing the database. + ## Database (`database`) - `DB_TYPE`: **mysql**: The database type in use \[mysql, postgres, mssql, sqlite3\]. diff --git a/docs/content/doc/features/authentication.en-us.md b/docs/content/doc/features/authentication.en-us.md index 7d555d1dcc4b0..ca98041c39e23 100644 --- a/docs/content/doc/features/authentication.en-us.md +++ b/docs/content/doc/features/authentication.en-us.md @@ -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`. - -**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. +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**: Once a user has been authenticated use of items such as SSH public +keys _may_ bypass the login check system. Therefore, if disabling a user, it +is recommended to manually disable the account in Gitea using the built-in user +manager as well. + +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) diff --git a/docs/content/doc/usage/reverse-proxies.en-us.md b/docs/content/doc/usage/reverse-proxies.en-us.md index 5797d8e5eb8f0..882148ff8de52 100644 --- a/docs/content/doc/usage/reverse-proxies.en-us.md +++ b/docs/content/doc/usage/reverse-proxies.en-us.md @@ -175,7 +175,7 @@ In case you already have a site, and you want Gitea to share the domain name, yo Then you **MUST** set something like `[server] ROOT_URL = http://git.example.com/git/` correctly in your configuration. -Note: The following Apache HTTPD mods must be enabled: `proxy`, `proxy_http`. +Note: The following Apache HTTPD mods must be enabled: `proxy`, `proxy_http`, additionally `lbmethod_byrequests` is required if proxying to https. ## Caddy From 0b2f6f8a5cac35a9c029861462af1db56edb0e59 Mon Sep 17 00:00:00 2001 From: Andrew Buettner Date: Sat, 19 Nov 2022 10:08:30 -0500 Subject: [PATCH 2/3] Addressing some PR feedback: - `lbmethod_byrequests` is actually not required for HTTPS. - `STATIC_URL_PREFIX` _should_ work on an uninitialized system (it doesn't on mine though. - Added several documentation improvements recommended by the project owners. --- .../doc/advanced/config-cheat-sheet.en-us.md | 19 +++++-------------- .../doc/usage/reverse-proxies.en-us.md | 2 +- 2 files changed, 6 insertions(+), 15 deletions(-) diff --git a/docs/content/doc/advanced/config-cheat-sheet.en-us.md b/docs/content/doc/advanced/config-cheat-sheet.en-us.md index 08847a64a6f32..92758c61e402e 100644 --- a/docs/content/doc/advanced/config-cheat-sheet.en-us.md +++ b/docs/content/doc/advanced/config-cheat-sheet.en-us.md @@ -289,17 +289,12 @@ 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/asset/css/index.css` and `https://cdn.example.com/asset/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. - Copy this directory to the `/static` location eg: `/var/www/static` and rename - it to `assets` eg:[^1] - -```bash -cd /var/www -mkdir static -cp -a $GITEA_BUILD/public static -mv static/public static/assets -``` + 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 @@ -416,10 +411,6 @@ mv static/public static/assets - `GRACEFUL_HAMMER_TIME`: **60s**: After a restart the parent process will stop accepting new connections and will allow requests to finish before stopping. Shutdown will be forced if it takes longer than this time. - `STARTUP_TIMEOUT`: **0**: Shutsdown the server if startup takes longer than the provided time. On Windows setting this sends a waithint to the SVC host to tell the SVC host startup may take some time. Please note startup is determined by the opening of the listeners - HTTP/HTTPS/SSH. Indexers may take longer to startup and can have their own timeouts. -[^1]: Gitea's initial configuration form will not work correctly with -`STATIC_URL_PREFIX` enabled. Use this option only after successfully deploying -Gitea and initializing the database. - ## Database (`database`) - `DB_TYPE`: **mysql**: The database type in use \[mysql, postgres, mssql, sqlite3\]. diff --git a/docs/content/doc/usage/reverse-proxies.en-us.md b/docs/content/doc/usage/reverse-proxies.en-us.md index 882148ff8de52..5797d8e5eb8f0 100644 --- a/docs/content/doc/usage/reverse-proxies.en-us.md +++ b/docs/content/doc/usage/reverse-proxies.en-us.md @@ -175,7 +175,7 @@ In case you already have a site, and you want Gitea to share the domain name, yo Then you **MUST** set something like `[server] ROOT_URL = http://git.example.com/git/` correctly in your configuration. -Note: The following Apache HTTPD mods must be enabled: `proxy`, `proxy_http`, additionally `lbmethod_byrequests` is required if proxying to https. +Note: The following Apache HTTPD mods must be enabled: `proxy`, `proxy_http`. ## Caddy From c43824e6ec5cc658b772219747f9fb00f484ec9a Mon Sep 17 00:00:00 2001 From: Andrew Buettner Date: Sun, 20 Nov 2022 09:40:47 -0500 Subject: [PATCH 3/3] Addressing additional PR comments: - Changed verbiage around use of SSH public keys. --- docs/content/doc/features/authentication.en-us.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/content/doc/features/authentication.en-us.md b/docs/content/doc/features/authentication.en-us.md index ca98041c39e23..f25065d9c48db 100644 --- a/docs/content/doc/features/authentication.en-us.md +++ b/docs/content/doc/features/authentication.en-us.md @@ -173,10 +173,10 @@ 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**: Once a user has been authenticated use of items such as SSH public -keys _may_ bypass the login check system. Therefore, if disabling a user, it -is recommended to manually disable the account in Gitea using the built-in user -manager as well. +**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.