docs: Install with galaxy and use docsmith
Signed-off-by: Julien Riou <julien@riou.xyz>
This commit is contained in:
parent
0fc90b71ef
commit
fe492d6188
GPG key ID:
9A099EDA51316854
5 changed files with 485 additions and 13 deletions
275
README.md
275
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
|
||||
|
||||
<!-- ANSIBLE DOCSMITH TOC START -->
|
||||
* [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)
|
||||
<!-- ANSIBLE DOCSMITH TOC END -->
|
||||
<!-- ANSIBLE DOCSMITH MAIN START -->
|
||||
|
||||
## Role variables<a id="variables"></a>
|
||||
|
||||
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<br><br>Define a `enabled` key with a boolean to enable the mailer<br><br>Define a `from` key with the source e-mail address<br><br>See [Email setup](https://forgejo.org/docs/latest/admin/setup/email/) |
|
||||
| `forgejo_service` | `dict` | No | N/A | Configure service settings<br><br>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<br><br>The key is the name of the repository on the instance<br><br>The value is the token |
|
||||
|
||||
### `forgejo_server`<a id="variable-forgejo_server"></a>
|
||||
|
||||
[*⇑ Back to ToC ⇑*](#toc)
|
||||
|
||||
Enable the server mode
|
||||
|
||||
- **Type**: `bool`
|
||||
- **Required**: No
|
||||
- **Default**: `true`
|
||||
|
||||
|
||||
|
||||
### `forgejo_version`<a id="variable-forgejo_version"></a>
|
||||
|
||||
[*⇑ Back to ToC ⇑*](#toc)
|
||||
|
||||
Version of the Forgejo binaries
|
||||
|
||||
- **Type**: `int`
|
||||
- **Required**: No
|
||||
- **Default**: `13`
|
||||
|
||||
|
||||
|
||||
### `forgejo_home_dir`<a id="variable-forgejo_home_dir"></a>
|
||||
|
||||
[*⇑ Back to ToC ⇑*](#toc)
|
||||
|
||||
Path to the home directory
|
||||
|
||||
- **Type**: `path`
|
||||
- **Required**: No
|
||||
- **Default**: `"/var/lib/forgejo"`
|
||||
|
||||
|
||||
|
||||
### `forgejo_config_dir`<a id="variable-forgejo_config_dir"></a>
|
||||
|
||||
[*⇑ Back to ToC ⇑*](#toc)
|
||||
|
||||
Path to the configuration directory
|
||||
|
||||
- **Type**: `path`
|
||||
- **Required**: No
|
||||
- **Default**: `"/etc/forgejo"`
|
||||
|
||||
|
||||
|
||||
### `forgejo_web_port`<a id="variable-forgejo_web_port"></a>
|
||||
|
||||
[*⇑ Back to ToC ⇑*](#toc)
|
||||
|
||||
Port to listen for the web UI
|
||||
|
||||
- **Type**: `int`
|
||||
- **Required**: No
|
||||
- **Default**: `3000`
|
||||
|
||||
|
||||
|
||||
### `forgejo_ssh_port`<a id="variable-forgejo_ssh_port"></a>
|
||||
|
||||
[*⇑ Back to ToC ⇑*](#toc)
|
||||
|
||||
Port to listen for SSH
|
||||
|
||||
- **Type**: `int`
|
||||
- **Required**: No
|
||||
- **Default**: `222`
|
||||
|
||||
|
||||
|
||||
### `forgejo_db_username`<a id="variable-forgejo_db_username"></a>
|
||||
|
||||
[*⇑ Back to ToC ⇑*](#toc)
|
||||
|
||||
Name of the user in the database
|
||||
|
||||
- **Type**: `str`
|
||||
- **Required**: No
|
||||
- **Default**: `"forgejo"`
|
||||
|
||||
|
||||
|
||||
### `forgejo_db_password`<a id="variable-forgejo_db_password"></a>
|
||||
|
||||
[*⇑ Back to ToC ⇑*](#toc)
|
||||
|
||||
Password of the user in the database
|
||||
|
||||
- **Type**: `str`
|
||||
- **Required**: Yes
|
||||
|
||||
|
||||
|
||||
### `forgejo_db_database`<a id="variable-forgejo_db_database"></a>
|
||||
|
||||
[*⇑ Back to ToC ⇑*](#toc)
|
||||
|
||||
Name of the database
|
||||
|
||||
- **Type**: `str`
|
||||
- **Required**: No
|
||||
- **Default**: `"forgejo"`
|
||||
|
||||
|
||||
|
||||
### `forgejo_mailer`<a id="variable-forgejo_mailer"></a>
|
||||
|
||||
[*⇑ 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`<a id="variable-forgejo_service"></a>
|
||||
|
||||
[*⇑ 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`<a id="variable-forgejo_manage_iptables"></a>
|
||||
|
||||
[*⇑ Back to ToC ⇑*](#toc)
|
||||
|
||||
Configure iptables rules
|
||||
|
||||
- **Type**: `bool`
|
||||
- **Required**: No
|
||||
- **Default**: `false`
|
||||
|
||||
|
||||
|
||||
### `forgejo_allowed_sources`<a id="variable-forgejo_allowed_sources"></a>
|
||||
|
||||
[*⇑ Back to ToC ⇑*](#toc)
|
||||
|
||||
List of IP ranges to allow when `forgejo_manage_iptables` is enabled
|
||||
|
||||
- **Type**: `list`
|
||||
- **Required**: No
|
||||
|
||||
|
||||
|
||||
### `forgejo_runners_version`<a id="variable-forgejo_runners_version"></a>
|
||||
|
||||
[*⇑ Back to ToC ⇑*](#toc)
|
||||
|
||||
Version of the runners
|
||||
|
||||
- **Type**: `str`
|
||||
- **Required**: No
|
||||
- **Default**: `"9.1.1"`
|
||||
|
||||
|
||||
|
||||
### `forgejo_runners_config_dir`<a id="variable-forgejo_runners_config_dir"></a>
|
||||
|
||||
[*⇑ Back to ToC ⇑*](#toc)
|
||||
|
||||
Path to the configuration directory of the runners
|
||||
|
||||
- **Type**: `path`
|
||||
- **Required**: No
|
||||
- **Default**: `"/etc/forgejo-runners"`
|
||||
|
||||
|
||||
|
||||
### `forgejo_runners_instance`<a id="variable-forgejo_runners_instance"></a>
|
||||
|
||||
[*⇑ Back to ToC ⇑*](#toc)
|
||||
|
||||
URL of the Forgejo instance to register the runners
|
||||
|
||||
- **Type**: `str`
|
||||
- **Required**: No
|
||||
|
||||
|
||||
|
||||
### `forgejo_runners`<a id="variable-forgejo_runners"></a>
|
||||
|
||||
[*⇑ 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
|
||||
|
||||
|
||||
|
||||
|
||||
<!-- ANSIBLE DOCSMITH MAIN END -->
|
||||
|
||||
## Usage
|
||||
|
||||
|
|
@ -33,7 +300,7 @@ Example of a basic forgejo.yml playbook:
|
|||
```yaml
|
||||
- hosts: forgejo
|
||||
roles:
|
||||
- forgejo
|
||||
- jriou.forgejo
|
||||
```
|
||||
|
||||
Then run the playbook:
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue