From fe492d618840078d04290443b0dedcd009ef38e7 Mon Sep 17 00:00:00 2001 From: Julien Riou Date: Sun, 15 Feb 2026 08:23:37 +0100 Subject: [PATCH] docs: Install with galaxy and use docsmith Signed-off-by: Julien Riou --- .gitignore | 1 + README.md | 275 +++++++++++++++++++++++++++++++++++++++- defaults/main.yml | 112 ++++++++++++++-- meta/argument_specs.yml | 106 ++++++++++++++++ tasks/deploy-server.yml | 4 + 5 files changed, 485 insertions(+), 13 deletions(-) create mode 100644 .gitignore create mode 100644 meta/argument_specs.yml diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..5ceb386 --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +venv diff --git a/README.md b/README.md index c3d04b6..da23734 100644 --- a/README.md +++ b/README.md @@ -4,10 +4,18 @@ Ansible role to manage a [Forgejo](https://forgejo.org/) instance. ## Installation -Clone the repository in your local Ansible roles directory: +Use Ansible Galaxy to install the role locally: ``` -git clone https://git.riou.xyz/jriou/ansible-role-forgejo.git ~/.ansible/roles/forgejo +ansible-galaxy role install git+https://git.riou.xyz/jriou/jriou.forgejo.git +``` + +Or use a requirements.yml file: + +```yaml +roles: + - src: git+https://git.riou.xyz/jriou/jriou.forgejo.git + type: git ``` See [Storing and finding @@ -23,8 +31,267 @@ Then define at least `forgejo_db_password` with a strong and secure password, encrypted using [ansible-vault](https://docs.ansible.com/ansible/latest/cli/ansible-vault.html). -See list of [default variables](defaults/main.yml). +## Table of Content + + +* [Role variables](#variables) + * [`forgejo_server`](#variable-forgejo_server) + * [`forgejo_version`](#variable-forgejo_version) + * [`forgejo_home_dir`](#variable-forgejo_home_dir) + * [`forgejo_config_dir`](#variable-forgejo_config_dir) + * [`forgejo_web_port`](#variable-forgejo_web_port) + * [`forgejo_ssh_port`](#variable-forgejo_ssh_port) + * [`forgejo_db_username`](#variable-forgejo_db_username) + * [`forgejo_db_password`](#variable-forgejo_db_password) + * [`forgejo_db_database`](#variable-forgejo_db_database) + * [`forgejo_mailer`](#variable-forgejo_mailer) + * [`forgejo_service`](#variable-forgejo_service) + * [`forgejo_manage_iptables`](#variable-forgejo_manage_iptables) + * [`forgejo_allowed_sources`](#variable-forgejo_allowed_sources) + * [`forgejo_runners_version`](#variable-forgejo_runners_version) + * [`forgejo_runners_config_dir`](#variable-forgejo_runners_config_dir) + * [`forgejo_runners_instance`](#variable-forgejo_runners_instance) + * [`forgejo_runners`](#variable-forgejo_runners) + + + +## Role variables + +The following variables can be configured for this role: + +| Variable | Type | Required | Default | Description (abstract) | +|----------|------|----------|---------|------------------------| +| `forgejo_server` | `bool` | No | `true` | Enable the server mode | +| `forgejo_version` | `int` | No | `13` | Version of the Forgejo binaries | +| `forgejo_home_dir` | `path` | No | `"/var/lib/forgejo"` | Path to the home directory | +| `forgejo_config_dir` | `path` | No | `"/etc/forgejo"` | Path to the configuration directory | +| `forgejo_web_port` | `int` | No | `3000` | Port to listen for the web UI | +| `forgejo_ssh_port` | `int` | No | `222` | Port to listen for SSH | +| `forgejo_db_username` | `str` | No | `"forgejo"` | Name of the user in the database | +| `forgejo_db_password` | `str` | Yes | N/A | Password of the user in the database | +| `forgejo_db_database` | `str` | No | `"forgejo"` | Name of the database | +| `forgejo_mailer` | `dict` | No | N/A | Configure the mailer to send e-mail notifications

Define a `enabled` key with a boolean to enable the mailer

Define a `from` key with the source e-mail address

See [Email setup](https://forgejo.org/docs/latest/admin/setup/email/) | +| `forgejo_service` | `dict` | No | N/A | Configure service settings

See [Service](https://forgejo.org/docs/latest/admin/config-cheat-sheet/#service-service) | +| `forgejo_manage_iptables` | `bool` | No | `false` | Configure iptables rules | +| `forgejo_allowed_sources` | `list` | No | N/A | List of IP ranges to allow when `forgejo_manage_iptables` is enabled | +| `forgejo_runners_version` | `str` | No | `"9.1.1"` | Version of the runners | +| `forgejo_runners_config_dir` | `path` | No | `"/etc/forgejo-runners"` | Path to the configuration directory of the runners | +| `forgejo_runners_instance` | `str` | No | N/A | URL of the Forgejo instance to register the runners | +| `forgejo_runners` | `dict` | No | N/A | List of runners to configure

The key is the name of the repository on the instance

The value is the token | + +### `forgejo_server` + +[*⇑ Back to ToC ⇑*](#toc) + +Enable the server mode + +- **Type**: `bool` +- **Required**: No +- **Default**: `true` + + + +### `forgejo_version` + +[*⇑ Back to ToC ⇑*](#toc) + +Version of the Forgejo binaries + +- **Type**: `int` +- **Required**: No +- **Default**: `13` + + + +### `forgejo_home_dir` + +[*⇑ Back to ToC ⇑*](#toc) + +Path to the home directory + +- **Type**: `path` +- **Required**: No +- **Default**: `"/var/lib/forgejo"` + + + +### `forgejo_config_dir` + +[*⇑ Back to ToC ⇑*](#toc) + +Path to the configuration directory + +- **Type**: `path` +- **Required**: No +- **Default**: `"/etc/forgejo"` + + + +### `forgejo_web_port` + +[*⇑ Back to ToC ⇑*](#toc) + +Port to listen for the web UI + +- **Type**: `int` +- **Required**: No +- **Default**: `3000` + + + +### `forgejo_ssh_port` + +[*⇑ Back to ToC ⇑*](#toc) + +Port to listen for SSH + +- **Type**: `int` +- **Required**: No +- **Default**: `222` + + + +### `forgejo_db_username` + +[*⇑ Back to ToC ⇑*](#toc) + +Name of the user in the database + +- **Type**: `str` +- **Required**: No +- **Default**: `"forgejo"` + + + +### `forgejo_db_password` + +[*⇑ Back to ToC ⇑*](#toc) + +Password of the user in the database + +- **Type**: `str` +- **Required**: Yes + + + +### `forgejo_db_database` + +[*⇑ Back to ToC ⇑*](#toc) + +Name of the database + +- **Type**: `str` +- **Required**: No +- **Default**: `"forgejo"` + + + +### `forgejo_mailer` + +[*⇑ Back to ToC ⇑*](#toc) + +Configure the mailer to send e-mail notifications + +Define a `enabled` key with a boolean to enable the mailer + +Define a `from` key with the source e-mail address + +See [Email setup](https://forgejo.org/docs/latest/admin/setup/email/) + +- **Type**: `dict` +- **Required**: No + + + +### `forgejo_service` + +[*⇑ Back to ToC ⇑*](#toc) + +Configure service settings + +See [Service](https://forgejo.org/docs/latest/admin/config-cheat-sheet/#service-service) + +- **Type**: `dict` +- **Required**: No + + + +### `forgejo_manage_iptables` + +[*⇑ Back to ToC ⇑*](#toc) + +Configure iptables rules + +- **Type**: `bool` +- **Required**: No +- **Default**: `false` + + + +### `forgejo_allowed_sources` + +[*⇑ Back to ToC ⇑*](#toc) + +List of IP ranges to allow when `forgejo_manage_iptables` is enabled + +- **Type**: `list` +- **Required**: No + + + +### `forgejo_runners_version` + +[*⇑ Back to ToC ⇑*](#toc) + +Version of the runners + +- **Type**: `str` +- **Required**: No +- **Default**: `"9.1.1"` + + + +### `forgejo_runners_config_dir` + +[*⇑ Back to ToC ⇑*](#toc) + +Path to the configuration directory of the runners + +- **Type**: `path` +- **Required**: No +- **Default**: `"/etc/forgejo-runners"` + + + +### `forgejo_runners_instance` + +[*⇑ Back to ToC ⇑*](#toc) + +URL of the Forgejo instance to register the runners + +- **Type**: `str` +- **Required**: No + + + +### `forgejo_runners` + +[*⇑ Back to ToC ⇑*](#toc) + +List of runners to configure + +The key is the name of the repository on the instance + +The value is the token + +- **Type**: `dict` +- **Required**: No + + + + + ## Usage @@ -33,7 +300,7 @@ Example of a basic forgejo.yml playbook: ```yaml - hosts: forgejo roles: - - forgejo + - jriou.forgejo ``` Then run the playbook: diff --git a/defaults/main.yml b/defaults/main.yml index 8a59374..cfb6503 100644 --- a/defaults/main.yml +++ b/defaults/main.yml @@ -1,26 +1,120 @@ --- + +# Enable the server mode +# +# - Type: bool +# - Required: No +# - Default: true forgejo_server: true + +# Version of the Forgejo binaries +# +# - Type: int +# - Required: No +# - Default: 13 forgejo_version: 13 + +# Path to the home directory +# +# - Type: path +# - Required: No +# - Default: /var/lib/forgejo forgejo_home_dir: /var/lib/forgejo + +# Path to the configuration directory +# +# - Type: path +# - Required: No +# - Default: /etc/forgejo forgejo_config_dir: /etc/forgejo + +# Port to listen for the web UI +# +# - Type: int +# - Required: No +# - Default: 3000 forgejo_web_port: 3000 + +# Port to listen for SSH +# +# - Type: int +# - Required: No +# - Default: 222 forgejo_ssh_port: 222 + +# Name of the user in the database +# +# - Type: str +# - Required: No +# - Default: forgejo forgejo_db_username: forgejo + +# Password of the user in the database +# +# - Type: str +# - Required: Yes forgejo_db_password: CHANGEME + +# Name of the database +# +# - Type: str +# - Required: No +# - Default: forgejo forgejo_db_database: forgejo -# forgejo_mailer: -# enabled: "true" -# from: email@test.eu -# https://forgejo.org/docs/latest/admin/setup/email/ + +# Configure the mailer to send e-mail notifications +# +# Define a `enabled` key with a boolean to enable the mailer +# +# Define a `from` key with the source e-mail address +# +# See +# +# - Type: dict +# - Required: No forgejo_mailer: {} -# forgejo_service: -# enable_notify_mail: "true" + +# Configure service settings +# +# See +# +# - Type: dict +# - Required: No forgejo_service: {} + +# Configure iptables rules +# +# - Type: bool +# - Required: No +# - Default: false forgejo_manage_iptables: false + +# List of IP ranges to allow when `forgejo_manage_iptables` is enabled +# +# - Type: list +# - Required: No forgejo_allowed_sources: [] + +# Version of the runners +# +# - Type: str +# - Required: No +# - Default: 9.1.1 forgejo_runners_version: 9.1.1 + +# Path to the configuration directory of the runners +# +# - Type: path +# - Required: No +# - Default: /etc/forgejo-runners forgejo_runners_config_dir: /etc/forgejo-runners -# forgejo_runners_instance: -# forgejo_runners: -# repository: token + +# List of runners to configure +# +# The key is the name of the repository on the instance +# +# The value is the token +# +# - Type: dict +# - Required: No forgejo_runners: {} diff --git a/meta/argument_specs.yml b/meta/argument_specs.yml new file mode 100644 index 0000000..8c82211 --- /dev/null +++ b/meta/argument_specs.yml @@ -0,0 +1,106 @@ +--- +argument_specs: + main: + short_description: Install and configure a Forgejo instance + description: + - Install and configure a [Forgejo](https://forgejo.org/) instance. + author: + - jriou + options: + forgejo_server: + description: + - Enable the server mode + type: bool + default: true + + forgejo_version: + description: + - Version of the Forgejo binaries + type: int + default: 13 + + forgejo_home_dir: + description: + - Path to the home directory + type: path + default: /var/lib/forgejo + + forgejo_config_dir: + description: + - Path to the configuration directory + type: path + default: /etc/forgejo + + forgejo_web_port: + description: + - Port to listen for the web UI + type: int + default: 3000 + + forgejo_ssh_port: + description: + - Port to listen for SSH + type: int + default: 222 + + forgejo_db_username: + description: + - Name of the user in the database + default: forgejo + + forgejo_db_password: + description: + - Password of the user in the database + required: true + + forgejo_db_database: + description: + - Name of the database + default: forgejo + + forgejo_mailer: + description: + - Configure the mailer to send e-mail notifications + - Define a `enabled` key with a boolean to enable the mailer + - Define a `from` key with the source e-mail address + - See [Email setup](https://forgejo.org/docs/latest/admin/setup/email/) + type: dict + + forgejo_service: + description: + - Configure service settings + - See [Service](https://forgejo.org/docs/latest/admin/config-cheat-sheet/#service-service) + type: dict + + forgejo_manage_iptables: + description: + - Configure iptables rules + type: bool + default: false + + forgejo_allowed_sources: + description: + - List of IP ranges to allow when `forgejo_manage_iptables` is enabled + type: list + + forgejo_runners_version: + description: + - Version of the runners + default: 9.1.1 + + forgejo_runners_config_dir: + description: + - Path to the configuration directory of the runners + type: path + default: /etc/forgejo-runners + + forgejo_runners_instance: + description: + - URL of the Forgejo instance to register the runners + + forgejo_runners: + description: + - List of runners to configure + - The key is the name of the repository on the instance + - The value is the token + type: dict diff --git a/tasks/deploy-server.yml b/tasks/deploy-server.yml index 7f13938..a2c7dbf 100644 --- a/tasks/deploy-server.yml +++ b/tasks/deploy-server.yml @@ -1,4 +1,8 @@ --- +- name: check database password + ansible.builtin.assert: + that: forgejo_db_password is defined + - name: create directories ansible.builtin.file: state: directory