ds_gitea/README.org

#+TITLE: Gitea Server Role
#+AUTHOR: DeadSwitch | The Silent Architect
#+OPTIONS: toc:nil num:nil \n:t

[[https://opensource.org/licenses/MIT][https://img.shields.io/badge/license-MIT-blue.svg]] [[https://img.shields.io/badge/version-3.0.3-green.svg]]

* ds_gitea

This role can install and configures a [[https://docs.gitea.com/][Gitea]] server.

- It uses SQLite as its default database service - with optional PostgreSQL support (=ds-posgresql=).
- The role can set up a reverse proxy with SSL using Nginx (=ds-nginx=).
- Self-signed certificates and Let's Encrypt with =certbot= are supported.
- The =ds-ufw= role can configure the firewall.
- The =ds-act_runner= role can configure and register Actions runners.

* Role Behavior

1. Download and install the Gitea binary
2. (Optionally) Set up the PostgreSQL user and database
3. (Optionally) Set up an =nginx= reverse proxy with SSL support
4. Create a user and group for the service
5. Create the required directory structure
6. Wait to save the secrets in SOPS (only if secrets are not present)
7. Deploy the Gitea =app.ini= configuration
8. Deploy the Gitea systemd service
9. Enable and start the services

* Defaults

#+begin_src yaml
gitea_user: git
gitea_group: git
gitea_http_port: 3000
gitea_ssh_port: 22
gitea_work_path: /var/lib/gitea
gitea_app_data_path: /var/lib/gitea/data
gitea_repo_root: /var/lib/gitea/data/gitea-repositories
gitea_lfs_path: /var/lib/gitea/data/lfs
gitea_log_path: /var/lib/gitea/log
gitea_require_signin_view: true
gitea_disable_registration: true
gitea_register_manual_confirm: false
gitea_enable_captcha: false
gitea_default_keep_email_private: true
#+end_src

* Requirements

- Ansible >= 2.12
- Debian 12+ or compatible
- git
- sudo
- ca-certificates
- (optional) PosgreSQL database
- (optional) Nginx server
- (optional) certbot for Let's Encrypt

* Variables

| Variable                         | Type    | Comment                                          |
|----------------------------------+---------+--------------------------------------------------|
| gitea_user                       | string  | Gitea user                                       |
| gitea_group                      | string  | Gitea group                                      |
| gitea_binary_url                 | string  | Download URL of Gitea                            |
| gitea_checksum_url               | string  | Checksum URL of the binary                       |
| gitea_app_name                   | string  | Gitea server title                               |
| gitea_ssh_domain                 | string  | SSH domain                                       |
| gitea_domain                     | string  | Domain to reach Gitea                            |
| gitea_http_port                  | int     | HTTP port                                        |
| gitea_ssh_port                   | int     | SSH port                                         |
| gitea_work_path                  | string  | Workdir                                          |
| gitea_app_data_path              | string  | Application data path                            |
| gitea_repo_root                  | string  | Repo root path                                   |
| gitea_lfs_path                   | string  | LFS path                                         |
| gitea_log_path                   | string  | Log path                                         |
| gitea_root_url                   | string  | Protocol + FQDN + port                           |
| gitea_lfs_jwt_secret             | string  | LFS storage secret                               |
| gitea_internal_token             | string  | Internal token                                   |
| gitea_jwt_secret                 | string  | JWT secret                                       |
| gitea_database_server            | string  | DB server - 'postgresql' or empty for sqlite     |
| gitea_db_password                | string  | PosgreSQL db password (if pgsql is used)         |
| gitea_reverse_proxy              | string  | Reverse proxy to use or not set for no proxy     |
| gitea_enable_https               | boolean | Configure HTTPS in the proxy                     |
| gitea_ssl_cert                   | string  | SSL certificate                                  |
| gitea_ssl_key                    | string  | SSL key                                          |
| gitea_enable_http_redirect       | boolean | Redirect HTTP to HTTPS                           |
| gitea_self_signed                | boolean | Generate a self-signed cert and key              |
| gitea_lets_encrypt               | boolean | Use certbot to configure the SSL                 |
| gitea_certbot_email              | string  | Email to register the certificates               |
| gitea_require_signin_view        | boolean | If false, public repos are visible without login |
| gitea_disable_registration       | boolean | Turn off the user registration feature           |
| gitea_register_manual_confirm    | boolean | Registration requires admin verification         |
| gitea_enable_captcha             | boolean | Enable captcha for registration                  |
| gitea_default_keep_email_private | boolean | Default email policy: private                    |

* Handlers

- =Reload_systemd=: It runs a =daemon-reload=
- =Restart_gitea=: It restarts the Gitea service

* Secrets

Always save the production secrets in SOPS, or in Ansible Vault.

You can generate the secrets manually when the playbook stops:

#+begin_src shell
gitea generate secret INTERNAL_TOKEN
gitea generate secret JWT_SECRET
#+end_src

Use the =JWT_SECRET= command to generate the =gitea_lfs_jwt_secret= as well. It's an alias.

Then re-run the playbook to finish the installation.

* Example Playbook

You can find more playbook examples in the =examples= directory.

#+begin_src yaml
- name: Deploy a Gitea server
  hosts: gitea
  become: true

  vars:
    gitea_user: git
    gitea_group: git
    gitea_binary_url: https://dl.gitea.com/gitea/1.25.4/gitea-1.25.4-linux-amd64
    gitea_checksum_url: https://dl.gitea.com/gitea/1.25.4/gitea-1.25.4-linux-amd64.sha256
    gitea_app_name: Tom's IT Cafe Gitea Server
    gitea_ssh_domain: gitea.tomsitcafe.com
    gitea_domain: gitea.tomsitcafe.com
    gitea_http_port: 3000
    gitea_root_url: https://gitea.tomsitcafe.com

    # Optional Postgresql database backend
    gitea_database_server: postgresql

    # Optional Nginx reverse proxy configuration
    gitea_reverse_proxy: nginx
    gitea_enable_https: true          # Use HTTPS
    gitea_self_signed: false          # Don't generate self-signed certs
    gitea_lets_encrypt: true          # Use certbot
    gitea_enable_http_redirect: true  # Redirect HTTP to HTTPS

    # Certbot configuration
    gitea_certbot_email: email@domain.tld
    gitea_ssl_cert: /etc/letsencrypt/live/{{ gitea_domain }}/fullchain.pem
    gitea_ssl_key: /etc/letsencrypt/live/{{ gitea_domain }}/privkey.pem
    gitea_ssl_trusted_certificate: /etc/letsencrypt/live/{{ gitea_domain }}/chain.pem 

    # In prod put the secrets in SOPS:
    gitea_lfs_jwt_secret: G9bZrRHMhRQ8w4R0KkH2VLnx2rzq81ROQ951IQjlMs4 
    gitea_internal_token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYmYiOjE3NzA2Mzk1Njh9.ybbaeNLFiLbyvxfj4vkqhXSAXKRGpwvP8jIm9YLPgXw
    gitea_jwt_secret: uJni4x4e0AzpkLYc-t4keRJKOB6EaLzwVsdLeamkFyU
    gitea_db_password: Eegh7Aothooph7pa6eu7eitha_zaim0G

  roles:
    - role: ds_gitea
#+end_src

* License

MIT

=[ Fear the Silence. Fear the Switch. ]=