Fix/selinux docs (#6066)

Signed-off-by: mehrdadbn9 <mehrdadbiukian@gmail.com>

docs/docs/20-usage/100-troubleshooting.md

@@ -35,3 +35,63 @@ git fetch --no-tags origin +refs/heads/branch:
 ```
 
 (replace the url AND the branch with the correct values, use your username and password as log in values)
+
+## SELinux Issues
+
+When running Woodpecker on systems with SELinux enabled (such as RHEL, CentOS, Fedora, or other Enterprise Linux distributions), SELinux may prevent the agent from accessing the Docker socket.
+
+### Symptoms
+
+If SELinux is blocking access, you may see errors like:
+
+```text
+permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock
+```
+
+### Solutions
+
+There are several ways to resolve this:
+
+#### Option 1: Set SELinux to Permissive Mode (For Testing Only)
+
+Set SELinux to permissive mode temporarily to verify it's the issue:
+
+```bash
+setenforce 0
+```
+
+To permanently set SELinux to permissive mode:
+
+```bash
+# Edit /etc/selinux/config
+SELINUX=permissive
+```
+
+#### Option 2: Configure SELinux Policy (Recommended)
+
+Create a custom SELinux policy to allow Woodpecker agent to access Docker:
+
+```bash
+# Generate the policy module
+ausearch -c 'docker' -avc | audit2allow -R -o woodpecker-docker.te
+# Build the policy module
+checkmodule -M -m -o woodpecker-docker.mod woodpecker-docker.te
+semodule_package -o woodpecker-docker.pp -m woodpecker-docker.mod
+# Load the policy module
+semodule -i woodpecker-docker.pp
+```
+
+#### Option 3: Use Docker Volume with SELinux Options
+
+When using Docker Compose or Docker, add the `:z` or `:Z` option to volume mounts:
+
+```yaml
+volumes:
+  - /var/run/docker.sock:/var/run/docker.sock:z
+```
+
+The `:z` option tells Docker to automatically relabel the volume content for SELinux. Use `:Z` with caution as it relabels the volume exclusively for this container.
+
+#### Option 4: Use Podman (Alternative)
+
+If you prefer to avoid SELinux configuration issues, consider using Podman instead of Docker, as it has better SELinux integration.

docs/docs/30-administration/05-installation/10-docker-compose.md

@@ -140,3 +140,14 @@ To store values in a docker secret you can use the following command:
 ```bash
 echo "my_agent_secret_key" | docker secret create woodpecker-agent-secret -
 ```
+
+## SELinux Considerations
+
+If you're running Woodpecker on a system with SELinux enabled (RHEL, CentOS, Fedora, etc.), you may need to add the `:z` or `:Z` option to volume mounts. For the Docker socket volume:
+
+```yaml
+volumes:
+  - /var/run/docker.sock:/var/run/docker.sock:z
+```
+
+For more details and other SELinux-related solutions, see the [Troubleshooting](../../20-usage/100-troubleshooting.md#selinux-issues) page.

docs/docs/30-administration/10-configuration/12-forges/30-gitea.md

@@ -33,8 +33,29 @@ To configure the Docker network if the network's name is `gitea`, configure it l
 
 ## Registration
 
+### User OAuth Application
+
 Register your application with Gitea to create your client id and secret. You can find the OAuth applications settings of Gitea at `https://gitea.<host>/user/settings/`. It is very important that authorization callback URL matches your http(s) scheme and hostname exactly with `https://<host>/authorize` as the path.
 
+### System-wide OAuth Application
+
+If you are the administrator of both Gitea and Woodpecker, you may prefer to use a system-wide OAuth application instead of a user-level application. System-wide applications are managed at the Gitea site administrator level and are visible to all users.
+
+To create a system-wide OAuth application in Gitea:
+
+1. Navigate to the site administration settings at `https://gitea.<host>/admin/settings/applications`
+2. Create a new OAuth2 application under the "OAuth2 Applications" section
+3. Configure the application with the same settings as above (callback URL, etc.)
+4. Use the generated client id and secret for Woodpecker configuration
+
+System-wide applications are particularly useful for:
+
+- Shared CI/CD environments where multiple users need Woodpecker access
+- Organizations that want centralized control over OAuth applications
+- Preventing user-level application quotas from affecting CI/CD operations
+
+### Local Connections
+
 If you run the Woodpecker CI server on the same host as the Gitea instance, you might also need to allow local connections in Gitea, since version `v1.16`. Otherwise webhooks will fail. Add the following lines to your Gitea configuration (usually at `/etc/gitea/conf/app.ini`).
 
 ```ini

docs/docs/30-administration/10-configuration/12-forges/35-forgejo.md

@@ -33,8 +33,29 @@ To configure the Docker network if the network's name is `forgejo`, configure it
 
 ## Registration
 
+### User OAuth Application
+
 Register your application with Forgejo to create your client id and secret. You can find the OAuth applications settings of Forgejo at `https://forgejo.<host>/user/settings/`. It is very important that authorization callback URL matches your http(s) scheme and hostname exactly with `https://<host>/authorize` as the path.
 
+### System-wide OAuth Application
+
+If you are the administrator of both Forgejo and Woodpecker, you may prefer to use a system-wide OAuth application instead of a user-level application. System-wide applications are managed at the Forgejo site administrator level and are visible to all users.
+
+To create a system-wide OAuth application in Forgejo:
+
+1. Navigate to the site administration settings at `https://forgejo.<host>/admin/settings/applications`
+2. Create a new OAuth2 application under the "OAuth2 Applications" section
+3. Configure the application with the same settings as above (callback URL, etc.)
+4. Use the generated client id and secret for Woodpecker configuration
+
+System-wide applications are particularly useful for:
+
+- Shared CI/CD environments where multiple users need Woodpecker access
+- Organizations that want centralized control over OAuth applications
+- Preventing user-level application quotas from affecting CI/CD operations
+
+### Local Connections
+
 If you run the Woodpecker CI server on the same host as the Forgejo instance, you might also need to allow local connections in Forgejo. Otherwise webhooks will fail. Add the following lines to your Forgejo configuration (usually at `/etc/forgejo/conf/app.ini`).
 
 ```ini