add some docs

diff --git a/docs/git-http.rst b/docs/git-http.rst
new file mode 100644 (file)
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 (file)
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 `<VERSION>` with the desired version (e.g., `1.21.4`).
+
+    .. code-block:: bash
+
+        sudo wget -O /usr/local/bin/gitea https://dl.gitea.com/gitea/<VERSION>/gitea-<VERSION>-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