From 41a18047ae13facac0065e13a7e533bbab2bd43a Mon Sep 17 00:00:00 2001 From: Shane Jaroch Date: Fri, 23 Jan 2026 17:22:59 -0500 Subject: [PATCH] add some docs --- docs/git-http.rst | 23 ++++++++ docs/gitea.rst | 133 ++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 156 insertions(+) create mode 100644 docs/git-http.rst create mode 100644 docs/gitea.rst diff --git a/docs/git-http.rst b/docs/git-http.rst new file mode 100644 index 0000000..a684c81 --- /dev/null +++ b/docs/git-http.rst @@ -0,0 +1,23 @@ +Git HTTP & Gitweb Configuration +=============================== + +This document covers the configuration and maintenance of the Git HTTP backend and Gitweb interface. + +Gitweb Owner Display +-------------------- + +By default, Gitweb displays the filesystem owner of the repository. However, the deployment script (`deploy.sh`) enforces `www-data:www-data` ownership on `/srv/git` for security and access reasons. This causes all repositories to show "www-data" as the owner in the Gitweb interface. + +To fix this **without changing file permissions**, you can set the `gitweb.owner` configuration variable inside each repository's `.git/config`. This adheres to the Gitweb configuration precedence and persists even after deployment scripts reset file ownership. + +**Command to set owner for all repositories:** + +.. code-block:: bash + + sudo find /srv/git -maxdepth 1 -name "*.git" -type d -exec git --git-dir="{}" config gitweb.owner "Shane J" \; + +**Why use this method?** + +* **Persistence:** `deploy.sh` resets filesystem permissions to `www-data` on every run. Setting `gitweb.owner` survives this. +* **Security:** Keeps the web server user (`www-data`) as the file owner, preventing permission errors. +* **Accuracy:** Allows displaying a human-readable name ("Shane J") instead of a system user. diff --git a/docs/gitea.rst b/docs/gitea.rst new file mode 100644 index 0000000..fbd8d20 --- /dev/null +++ b/docs/gitea.rst @@ -0,0 +1,133 @@ +Gitea Maintenance (Backup & Update) +===================================== + +This document outlines the procedures for backing up and updating the Gitea instance. + +Backup +------ + +We use a custom script located on the local machine (e.g., `~/.backups/pg_backups`) to trigger a remote backup and pull the archive. + +**Usage:** + +.. code-block:: bash + + # Run from your local machine + ~/.backups/pg_backups/gitea-backup.sh + +**Configuration:** + +You can override the defaults using environment variables: + +.. code-block:: bash + + HOST="my-gitea.server" SSH_USER="admin" ~/.backups/pg_backups/gitea-backup.sh + +**Prerequisites (Sudo Access):** + +Since the script runs non-interactively, your SSH user must be able to run `gitea` commands as the Gitea user without a password. + +On the **Gitea Server**, add this to `/etc/sudoers` (using `sudo visudo`): + +.. code-block:: text + + # Allow shane to run commands as gg without a password + shane ALL=(gg) NOPASSWD: /usr/local/bin/gitea + +**What it does:** + +1. SSHs into the Gitea server and triggers a dump. +2. Downloads the zip file to your local machine (`~/.backups/pg_backups/gitea/`). +3. **Local Processing:** + * Unzips the backup. + * Converts `gitea.db` (SQLite) to `gitea.sql` (Text) for easier version control (requires local `sqlite3`). + * Compresses large binary folders (`repos`, `data`, `log`) into `assets.tar.xz`. + * Deletes the extracted binaries to keep the repo clean. + +**Resulting Structure:** + +* `.gitea-sqlite/app.ini` (Text Config) +* `.gitea-sqlite/gitea.db` (SQLite Database - Handled by `git-sqlite-filter`) +* `.gitea-sqlite/gitea-db.sql` (SQL Dump - Redundant but safe to keep) +* `.gitea-sqlite/custom/` (Templates, Public Assets, Configs - Kept as files) +* `.gitea-sqlite/data/` (Site Data - Kept as files) +* `.gitea-sqlite/log/` (Logs - Kept as files) +* *(Repositories are excluded from this backup)* + +Prerequisites (Sudo Access) +--------------------------- + +The script uses `gitea-remote-dump.sh` which runs `gitea dump` on the server. +Since Gitea is installed as a binary at `/usr/local/bin/gitea`, ensure your user has sudo execution rights. + +**Reducing Backup Size:** +If your backups are large (e.g., hundreds of MBs), it's likely due to **repo-archive**. This folder stores cached zip/tar.gz files generated when users download repository sources. + +* **Status:** Safe to delete. They are regenerated on demand. +* **Action:** You can delete them manually or via cron to save space. + + **Method 1: Via Gitea Interface (Recommended)** + + 1. Log in as a site administrator. + 2. Go to **Site Administration** > **Monitor** (or **Maintenance**). + 3. Find **Cron Tasks**. + 4. Locate **Delete all repository archives** and click **Run**. + + **Method 2: Via CLI** + + .. code-block:: bash + + # On the server + sudo -u gg rm -rf /var/lib/gitea/data/repo-archive/* + +Update Procedure +---------------- + +To update Gitea, you replace the binary file. + +**Prerequisites:** + +* Check the latest version on [Gitea Releases](https://github.com/go-gitea/gitea/releases). +* Ensure you have `sudo` access. + +**Steps:** + +1. **Stop the Service:** + + .. code-block:: bash + + sudo systemctl stop gitea-web + +2. **Backup Current Binary:** + + .. code-block:: bash + + sudo cp /usr/local/bin/gitea /usr/local/bin/gitea.bak + +3. **Download New Version:** + + Replace `` with the desired version (e.g., `1.21.4`). + + .. code-block:: bash + + sudo wget -O /usr/local/bin/gitea https://dl.gitea.com/gitea//gitea--linux-amd64 + +4. **Make Executable:** + + .. code-block:: bash + + sudo chmod +x /usr/local/bin/gitea + +5. **Restart Service:** + + .. code-block:: bash + + sudo systemctl start gitea-web + +6. **Verify:** + + Check the status and logs to ensure it started correctly. + + .. code-block:: bash + + sudo systemctl status gitea-web -- 2.52.0