docs(gitea_server): Added role README

Added new role README with info about the role, and detailed variable breakdown.
2026-07-12 14:58:57 -07:00
parent ed6e97cddc
commit fdb3eca541
1 changed files with 124 additions and 0 deletions
@@ -0,0 +1,124 @@
+# Role: Gitea Server
+Sets up and deploys Gitea server and Act Runner. 
+It is recommended that only one server have this role. This prevents issues with multiple sources of truth.
+
+## Tags
+- core
+- gitea
+
+## Required Variables
+Below is an annotated breakdown of the required variables and their structure for this role
+
+These blocks should be defined in the `host_vars` file for the host you wish to be the designated gitea server
+
+> [!WARNING]
+> Any variable marked `# !SENSITIVE` **should not** be stored in plain text under any circumstance
+
+### Gitea Info
+Defines settings for the Gitea container to be deployed
+
+```yaml
+# (required) List of all Gitea containers to be deployed
+# in theory you can run multiple containers, however it is highly recommend to only run one
+# at least one service is required
+gitea_services:
+
+    # (required) name of the container in podman, and service name in systemd
+    # This is unique to both podman and systemd
+    # format: snake_case
+  - name:
+
+    # (required) URL of container image
+    # can be from any container registry
+    # format: url
+    image:
+
+    # (optional) name of container owner
+    # best practice is to use the name of the user running this container
+    # default: "jdelpilar"
+    # format: string
+    container_owner:
+
+    # --- Traefik Labels --- #
+    # (optional) subdomain for the WebUI of the container
+    # This is used to build the FQDN that traefik will use
+    # default: name value defined above
+    # format: snake_case
+    subdomain:
+
+    # (optional) domain used in FQDN
+    # default: "delpilar.net"
+    # format: URL (domain only)
+    domain:
+
+    # (optional) Port of the WebUI as defined by the container
+    # Please check the documentation of the specific container used to find this value
+    # default: 80
+    # format: int
+    port: 3000
+
+    # (optional) list of volume mounts to be used by the container
+    # it is highly recommended to use volume mounts for Gitea containers to persist configs
+    # format example is listed below
+    # default: []
+    # format: /local/path/:/container/path
+    volumes:
+      - /local/path:/container/path
+```
+### Act Runner Info
+Defines settings for the Act Runner container to be deployed
+
+```yaml
+
+# (required) List of all Act Runner containers to be deployed
+# defining multiple runners may result in better concurrency
+# however for most users, one runner will be enough
+# at least one service is required
+runner_services:
+
+    # (required) name of the container in podman, and service name in systemd
+    # This is unique to both podman and systemd
+    # format: snake_case
+  - name:
+
+    # (required) URL of container image
+    # can be from any container registry
+    # format: url
+    image:
+
+
+    # (optional) name of container owner
+    # best practice is to use the name of the user running this container
+    # default: "jdelpilar"
+    # format: string
+    container_owner:
+
+    # (required) URL of the gitea instance
+    # should match the URL generated by the subdomain and domain variables for the gitea service
+    # format: URL
+    gitea_url:
+
+    # (required) Unique token for the runner. Authenticates the runner to gitea
+    # Must be generated via the gitea instance. Any value can be used to allow this role to set up gitea
+    # format: string
+    # !SENSITIVE
+    runner_token:
+```
+
+
+## Templates
+
+### gitea_quadlet.j2
+This template is used to generate .container files for Gitea services. This template includes a section for traefik labels.
+
+### act_runner_quadlet.j2
+This template is used to generate .container files for act_runner services. 
+
+## Execution
+> [!CAUTION]
+> This role targets and can potentially restart core services. As such it is recommended to only run this role when 100% necessary 
+
+To run this command without running all roles in the playbook, use the following command
+```bash
+ansible-playbook site.yaml --tags "gitea"
+```