Merge pull request #3 from roles-ansible/docs

continue reordering variable names

README.md

@@ -66,29 +66,94 @@ Here is a deeper insight into the variables of this gitea role. For the exact fu
 ### gitea in the linux world
 | variable name | default value | description |
 | ------------- | ------------- | ----------- |
-| `gitea_user` | `gitea ` | UNIX user used by Gitea |
 | `gitea_group` | `gitea` | UNIX group used by Gitea |
 | `gitea_home` | `/var/lib/gitea` | Base directory to work |
 | `gitea_shell` | `/bin/false` | UNIX shell used by gitea. Set it to `/bin/bash` if you don't use the gitea built-in ssh server. |
 
-### Look and feel
+### Overall ([DEFAULT](https://docs.gitea.io/en-us/config-cheat-sheet/#overall-default))
 | variable name | default value | description |
 | ------------- | ------------- | ----------- |
 | `gitea_app_name` | `Gitea` | Displayed application name |
-| `gitea_repository_root` | `{{ gitea_home }}/repos` | The path where all gitea repositorys are stored |
+| `gitea_user` | `gitea ` | UNIX user used by Gitea |
+| `gitea_run_mode`| `prod`| Application run mode, affects performance and debugging. Either “dev”, “prod” or “test”. |
+
+### Repository ([repository](https://docs.gitea.io/en-us/config-cheat-sheet/#repository-repository))
+| variable name | default value | description |
+| ------------- | ------------- | ----------- |
+| `gitea_repository_root` | `{{ gitea_home }}/repos` |  Root path for storing all repository data. It must be an absolute path. |
+| `gitea_force_private` | `false` | Force every new repository to be private. |
+| `gitea_user_repo_limit` | `-1` | Limit how many repos a user can have *(`-1` for unlimited)* |
+| `gitea_disable_http_git` | `false` | Disable the ability to interact with repositories over the HTTP protocol. (true/false) |
+| `gitea_default_branch` | `main` | Default branch name of all repositories. |
+| `gitea_repository_extra_config` | `''` | you can use this variable to pass additional config parameters in the `[repository]` section of the config. |
+
+### UI ([ui](https://docs.gitea.io/en-us/config-cheat-sheet/#ui-ui))
+| variable name | default value | description |
+| ------------- | ------------- | ----------- |
 | `gitea_show_user_email` | `false` | Do you want to display email addresses ? (true/false) |
+| `gitea_theme_default` | `gitea` | Default theme |
+| `gitea_themes` | `gitea,arc-green` | List of enabled themes |
+| `gitea_ui_extra_config` | `''` | you can use this variable to pass additional config parameters in the `[ui]` section of the config. |
+
+### Server ([server](https://docs.gitea.io/en-us/config-cheat-sheet/#server-server))
+| variable name | default value | description |
+| ------------- | ------------- | ----------- |
+| `gitea_protocol`| `http` | Listening protocol [http, https, fcgi, unix, fcgi+unix] |
+| `gitea_http_domain` | `localhost` | Domain name of this server. Set it to the FQDN where you can reach your gitea server |
+| `gitea_root_url` | `http://localhost:3000` | Root URL used to access your web app (full URL) |
+| `gitea_http_listen` | `127.0.0.1` | HTTP listen address |
+| `gitea_http_port` | `3000` | Bind port *(redirect from `80` will be activated if value is `443`)* |
+| `gitea_http_letsencrypt_mail` | `undefined` | Enable Let`s Encrypt if a email address is given |
+| `gitea_start_ssh` | `true` | When enabled, use the built-in SSH server. |
+| `gitea_ssh_domain` | `{{ gitea_http_domain ` |  Domain name of this server, used for displayed clone URL |
+| `gitea_ssh_port` | `2222` | SSH port displayed in clone URL. |
+| `gitea_ssh_listen` | `0.0.0.0` | Listen address for the built-in SSH server. |
+| `gitea_offline_mode` | `true` | Disables use of CDN for static files and Gravatar for profile pictures. (true/false) |
+| `gitea_lfs_enabled` | `false` | Enable GIT-LFS Support *(git large file storeage: [git-lfs](https://git-lfs.github.com/))*. |
+| `gitea_lfs_content_path` | `{{ gitea_home }}/data/lfs` |  LFS content path. *(if it is on local storage.)* |
+| `gitea_lfs_jwt_secret` | `''` | LFS authentication secret. Can be generated with ``gitea generate secret JWT_SECRET``. Will be autogenerated if not defined |
+| `gitea_server_extra_config` | `''` | you can use this variable to pass additional config parameters in the `[ui]` section of the config. |
+
+### Database ([database](https://docs.gitea.io/en-us/config-cheat-sheet/#database-database))
+| variable name | default value | description |
+| ------------- | ------------- | ----------- |
+| `gitea_db_type` | `sqlite3` | The database type in use `[mysql, postgres, mssql, sqlite3]`. |
+| `gitea_db_host` | `127.0.0.0:3306` | Database host address and port or absolute path for unix socket [mysql, postgres] (ex: `/var/run/mysqld/mysqld.sock`). |
+| `gitea_db_name` | `root` | Database name |
+| `gitea_db_user` | `gitea` | Database username |
+| `gitea_db_password` | `lel` | Database password. **PLEASE CHANGE** |
+| `gitea_db_ssl` | `disable` | Configure SSL only if your database type supports it. Have a look into the [config-cheat-sheet](https://docs.gitea.io/en-us/config-cheat-sheet/#database-database) for more detailed information |
+| `gitea_db_path` | `{{ gitea_home }}/data/gitea.db` | DB path, if you use `sqlite3`. |
+| `gitea_database_extra_config` | `''` | you can use this variable to pass additional config parameters in the `[database]` section of the config. |
+
+### Indexer ([indexer](https://docs.gitea.io/en-us/config-cheat-sheet/#indexer-indexer))
+| variable name | default value | description |
+| ------------- | ------------- | ----------- |
+| `gitea_repo_indexer_enabled` | `false` | Enables code search *(uses a lot of disk space, about 6 times more than the repository size).* |
+| `gitea_repo_indexer_include` | `''` |Glob patterns to include in the index *(comma-separated list)*. An empty list means include all files. |
+| `gitea_repo_indexer_exclude` | `''` | Glob patterns to exclude from the index (comma-separated list). |
+| `gitea_repo_exclude_vendored` | `true` | Exclude vendored files from index. |
+| `gitea_repo_indexer_max_file_size` | `1048576` | Maximum size in bytes of files to be indexed. |
+| `gitea_indexer_extra_config` | `''` | you can use this variable to pass additional config parameters in the `[indexer]` section of the config. |
+
+
+
+
+
+
+
+### Look and feel
+| variable name | default value | description |
+| ------------- | ------------- | ----------- |
 | `gitea_disable_gravatar` | `true` | Do you want to disable Gravatar ? (privacy and so on) (true/false) |
 | `gitea_disable_registration` | `false` | Do you want to disable user registration? (true/false) |
 | `gitea_register_email_confirm` | `false` | Enable this to ask for mail confirmation of registration. Requires `gitea_mailer_enabled` to be enabled. |
-| `gitea_offline_mode` | `true` | Disables use of CDN for static files and Gravatar for profile pictures. (true/false) |
 | `gitea_only_allow_external_registration` | `false` | Set to true to force registration only using third-party services (true/false) |
 | `gitea_show_registration_button` | `true` | Here you can hide the registration button. This will not disable registration! (true/false)|
 | `gitea_require_signin` | `true` | Do you require a signin to see repo's (even public ones)? (true/false)|
 | `gitea_enable_captcha` | `true` | Do you want to enable captcha's ? (true/false)|
 | `gitea_enable_notify_mail` | `false` | Enable this to send e-mail to watchers of a repository when something happens, like creating issues (true/false) |
 | `gitea_auto_watch_new_repos` | `true` | Enable this to let all organisation users watch new repos when they are created (true/false) |
-| `gitea_themes` | `gitea,arc-green` | List of enabled themes |
-| `gitea_theme_default` | `gitea` | Default theme |
 
 
 ### Security
@@ -97,38 +162,17 @@ Here is a deeper insight into the variables of this gitea role. For the exact fu
 | `gitea_secret_key` | `''` | Global secret key. Will be autogenerated if not defined. Should be unique. |
 | `gitea_internal_token` | `''` | Internal API token. Will be autogenerated if not defined. Should be unique. |
 | `gitea_disable_git_hooks` | `true` | Set to false to enable users with git hook privilege to create custom git hooks. Can be dangerous. |
-| `gitea_user_repo_limit` | `-1` | Limit how many repos a user can have *(`-1` for unlimited)* |
-| `gitea_lfs_secret` | `''` | < JWT secret for remote LFS usage. Can be generated with ``gitea generate secret JWT_SECRET``. Will be autogenerated if not defined |
 | `gitea_oauth2_jwt_secret` | `''` | Oauth2 JWT secret. Can be generated with ``gitea generate secret JWT_SECRET``. Will be autogenerated if not defined. |
 
 
 ### HTTP configuration
 
-* `gitea_http_domain`: HTTP domain (displayed in your clone URLs, just the domain like git.foo.fr)
-* `gitea_root_url`: Root URL used to access your web app (full URL)
-* `gitea_protocol`: Listening protocol (http/https)
-* `gitea_http_listen`: Bind address
-* `gitea_http_port`: Bind port (redirect from `80` will be activated if value is `443` - Default: `3000`)
-* `gitea_disable_http_git`: Disable the use of Git over HTTP ? (true/false)
-* `gitea_http_letsencrypt_mail` Enable Let`s Encrypt if a email address is given
 
 ### SSH configuration
 
-* `gitea_ssh_listen`: Bind address for the SSH server
-* `gitea_ssh_domain`: SSH domain (displayed in your clone URLs)
-* `gitea_start_ssh`: Do you want to start a built-in SSH server ? (true/false)
-* `gitea_ssh_port`: SSH bind port
 
 ### Database configuration
 
-* `gitea_db_type`: Database type, can be `mysql`, `postgres` or `sqlite3`
-* `gitea_db_host`: Database host string `host:port` or `/run/postgresql/` when connectiong to postgres via local unix socket (peer authentication)
-* `gitea_db_name`: Database name
-* `gitea_db_user`: Database username
-* `gitea_db_password`: Database password
-* `gitea_db_ssl`: Use SSL ? (postgres only!). Can be `require`, `disable`, `verify-ca` or `verify-full`
-* `gitea_db_path`: DB path, if you use `sqlite3`. The default is good enough to work though.
-
 ### Mailer configuration
 
 * `gitea_mailer_enabled`: Whether to enable the mailer. Default: `false`
@@ -143,8 +187,6 @@ Here is a deeper insight into the variables of this gitea role. For the exact fu
 
 ### LFS configuration
 
-* `gitea_lfs_enabled`: Enable GIT LFS *(git large file storeage: [git-lfs](https://git-lfs.github.com/))*. Default: `false`
-* `gitea_lfs_content_path`: path where the lfs files are stored
 
 ### Log configuration
 * `gitea_log_systemd` Disable logging into `file`, use systemd-journald
@@ -174,11 +216,6 @@ As this will only deploy config files, fail2ban already has to be installed or o
 
 ### Repository Indexer configuration
 
-* `gitea_repo_indexer_enabled`: Whether to enable the repository indexer (code search). Default: `false`
-* `gitea_repo_indexer_include`: Glob patterns to include in the index (comma-separated list). Default: `""` (all files)
-* `gitea_repo_indexer_exclude`: Glob patterns to exclude from the index (comma-separated list). Default: `""` (no files)
-* `gitea_repo_exclude_vendored`: Exclude vendored files from the index. Default: `true`
-* `gitea_repo_indexer_max_file_size`: Maximum size of files to be indexed (in bytes). Default: `1048576` (1 MB)
 
 ### backup on upgrade
 * `gitea_backup_on_upgrade`: Optionally a backup can be created with every update of gitea. Default: `false`

defaults/main.yml

@@ -1,70 +1,93 @@
 ---
 # gitea version
-gitea_version: "1.13.4"
+gitea_version: '1.13.4'
 gitea_version_check: true
 gitea_dl_url: "https://github.com/go-gitea/gitea/releases/download/v{{ gitea_version }}/gitea-{{ gitea_version }}-linux-{{ gitea_arch }}"
-gitea_gpg_key: "7C9E68152594688862D62AF62D9AE806EC1592E2"
+gitea_gpg_key: '7C9E68152594688862D62AF62D9AE806EC1592E2'
-gitea_gpg_server: "hkp://keyserver.ubuntu.com:80"
+gitea_gpg_server: 'hkp://keyserver.ubuntu.com:80'
 
 # gitea in the linux world
-gitea_user: "gitea"
+gitea_group: 'gitea'
-gitea_group: "gitea"
+gitea_home: '/var/lib/gitea'
-gitea_home: "/var/lib/gitea"
+gitea_shell: '/bin/false'
-gitea_shell: "/bin/false"
+
+# Overall (DEFAULT)
+# -> https://docs.gitea.io/en-us/config-cheat-sheet/#overall-default
+gitea_app_name: 'Gitea'
+gitea_user: 'gitea'
+gitea_run_mode: 'prod'
+
+# Repository (repository)
+# -> https://docs.gitea.io/en-us/config-cheat-sheet/#repository-repository
+gitea_repository_root: "{{ gitea_home }}/repos"
+gitea_force_private: false
+gitea_user_repo_limit: '-1'
+gitea_disable_http_git: false
+gitea_default_branch: 'main'
+gitea_repository_extra_config: ''
+
+# UI (ui)
+# -> https://docs.gitea.io/en-us/config-cheat-sheet/#ui-ui
+gitea_show_user_email: false
+gitea_theme_default: 'gitea'
+gitea_themes: 'gitea,arc-green'
+gitea_ui_extra_config: ''
+
+# Server (server)
+# -> https://docs.gitea.io/en-us/config-cheat-sheet/#server-server
+gitea_protocol: 'http'
+gitea_http_domain: 'localhost'
+gitea_root_url: 'http://localhost:3000'
+gitea_http_listen: '127.0.0.1'
+gitea_http_port: '3000'
+# gitea_http_letsencrypt_mail: 'mail@example.com'
+gitea_start_ssh: true
+gitea_ssh_domain: "{{ gitea_http_domain }}"
+gitea_ssh_port: '2222'
+gitea_ssh_listen: '0.0.0.0'
+gitea_offline_mode: true
+gitea_lfs_server_enabled: false
+gitea_lfs_content_path: "{{ gitea_home }}/data/lfs"
+gitea_server_extra_config: ''
+
+# Database (database)
+# -> https://docs.gitea.io/en-us/config-cheat-sheet/#database-database
+gitea_db_type: 'sqlite3'
+gitea_db_host: '127.0.0.0:3306'
+gitea_db_name: 'root'
+gitea_db_user: 'gitea'
+gitea_db_password: 'lel'
+gitea_db_ssl: 'disable'
+gitea_db_path: "{{ gitea_home }}/data/gitea.db"
+
+# Indexer (indexer)
+# -> https://docs.gitea.io/en-us/config-cheat-sheet/#indexer-indexer
+gitea_repo_indexer_enabled: false
+gitea_repo_indexer_include: ''
+gitea_repo_indexer_exclude: ''
+gitea_repo_exclude_vendored: true
+gitea_repo_indexer_max_file_size: '1048576'
+gitea_indexer_extra_config: ''
 
 # look and feel
-gitea_app_name: "Gitea"
-gitea_repository_root: "{{ gitea_home }}/repos"
-gitea_show_user_email: false
 gitea_disable_gravatar: true
 gitea_disable_registration: false
 gitea_register_email_confirm: false
-gitea_offline_mode: true
 gitea_only_allow_external_registration: false
 gitea_show_registration_button: true
 gitea_require_signin: true
 gitea_enable_captcha: true
 gitea_enable_notify_mail: false
 gitea_auto_watch_new_repos: true
-gitea_themes: gitea,arc-green
-gitea_theme_default: gitea
 
 # security
 gitea_secret_key: ''
 gitea_internal_token: ''
 gitea_disable_git_hooks: true
-gitea_user_repo_limit: -1
 gitea_lfs_jwt_secret: ''
 gitea_oauth2_jwt_secret: ''
 
-gitea_http_domain: localhost
-
-gitea_root_url: http://localhost:3000
-gitea_protocol: http
-gitea_http_listen: 127.0.0.1
-gitea_http_port: 3000
-# gitea_http_letsencrypt_mail:  - required
-gitea_disable_http_git: false
-
-
-gitea_lfs_server_enabled: false
-gitea_lfs_content_path: "{{ gitea_home }}/data/lfs"
-
 gitea_systemd_cap_net_bind_service: false
-gitea_db_type: sqlite3
-gitea_db_host: 127.0.0.0:3306
-gitea_db_name: root
-gitea_db_user: gitea
-gitea_db_password: lel
-gitea_db_ssl: disable
-gitea_db_path: "{{ gitea_home }}/data/gitea.db"
-
-gitea_ssh_listen: 0.0.0.0
-gitea_ssh_domain: localhost
-gitea_start_ssh: true
-gitea_ssh_port: 2222
-
-gitea_force_private: false
 
 gitea_mailer_enabled: false
 gitea_mailer_skip_verify: false
@@ -90,13 +113,6 @@ gitea_oauth2_enabled: true
 gitea_metrics_enabled: false
 gitea_metrics_token: ~
 
-
-gitea_repo_indexer_enabled: false
-gitea_repo_indexer_include: ""
-gitea_repo_indexer_exclude: ""
-gitea_repo_exclude_vendored: true
-gitea_repo_indexer_max_file_size: 1048576
-
 gitea_log_level: Info
 
 gitea_extra_config: ""

templates/gitea.ini.j2

@@ -5,36 +5,35 @@
 ; undefined variables will use the default value from gitea.
 ; Cheat Sheet: https://docs.gitea.io/en-us/config-cheat-sheet/
 ;
-; App name that shows on every page title
+; -> https://docs.gitea.io/en-us/config-cheat-sheet/#overall-default
 APP_NAME = {{ gitea_app_name }}
-; Change it if you run locally
 RUN_USER = {{ gitea_user }}
-; Either "dev", "prod" or "test", default is "dev"
+RUN_MODE = {{ gitea_run_mode }}
-RUN_MODE = prod
+;
-
+;
+; -> https://docs.gitea.io/en-us/config-cheat-sheet/#repository-repository
 [repository]
 ROOT                = {{ gitea_repository_root }}
-; Force every new repository to be private
 FORCE_PRIVATE       = {{ gitea_force_private | ternary('true', 'false') }}
-; Global limit of repositories per user, applied at creation time. -1 means no limit
 MAX_CREATION_LIMIT  = {{ gitea_user_repo_limit }}
-; Mirror sync queue length, increase if mirror syncing starts hanging
-MIRROR_QUEUE_LENGTH = 1000
-; Disable the ability to interact with repositories using the HTTP protocol
 DISABLE_HTTP_GIT    = {{ gitea_disable_http_git | ternary('true', 'false') }}
-
+DEFAULT_BRANCH      = {{ gitea_default_branch }}
+{{ gitea_repository_extra_config }}
+;
+;
+; -> https://docs.gitea.io/en-us/config-cheat-sheet/#ui-ui
 [ui]
-; Whether the email of the user should be shown in the Explore Users page
 SHOW_USER_EMAIL = {{ gitea_show_user_email | ternary('true', 'false') }}
-THEMES          = {{ gitea_themes }}
 DEFAULT_THEME   = {{ gitea_theme_default }}
-
+THEMES          = {{ gitea_themes }}
+{{ gitea_ui_extra_config }}
+;
+;
+; -> https://docs.gitea.io/en-us/config-cheat-sheet/#server-server
 [server]
-; The protocol the server listens on. One of 'http', 'https', 'unix' or 'fcgi'.
 PROTOCOL              = {{ gitea_protocol }}
 DOMAIN                = {{ gitea_http_domain }}
 ROOT_URL              = {{ gitea_root_url }}
-; The address to listen on. Either a IPv4/IPv6 address or the path to a unix socket.
 HTTP_ADDR             = {{ gitea_http_listen }}
 HTTP_PORT             = {{ gitea_http_port }}
 {% if gitea_http_port == 443 %}
@@ -45,63 +44,50 @@ ENABLE_LETSENCRYPT    = true
 LETSENCRYPT_ACCEPTTOS = true
 LETSENCRYPT_EMAIL     = {{ gitea_http_letsencrypt_mail }}
 {% endif %}
-; Disable SSH feature when not available
-DISABLE_SSH      = false
-; Whether to use the builtin SSH server or not.
 START_SSH_SERVER      = {{ gitea_start_ssh | ternary('true', 'false') }}
-; Domain name to be exposed in clone URL
 SSH_DOMAIN            = {{ gitea_ssh_domain }}
-; The network interface the builtin SSH server should listen on
-SSH_LISTEN_HOST  = {{ gitea_ssh_listen }}
-; Port number to be exposed in clone URL
 SSH_PORT              = {{ gitea_ssh_port }}
-; The port number the builtin SSH server should listen on
+SSH_LISTEN_HOST       = {{ gitea_ssh_listen }}
-SSH_LISTEN_PORT  = %(SSH_PORT)s
-; Disable CDN even in "prod" mode
 OFFLINE_MODE          = {{ gitea_offline_mode | ternary('true', 'false') }}
-; Default path for App data
 APP_DATA_PATH         = {{ gitea_home }}/data
 {% if gitea_lfs_server_enabled | bool -%}
-;Enables git-lfs support.
 LFS_START_SERVER      = true
-; Where to store LFS files.
 LFS_CONTENT_PATH      = {{ gitea_lfs_content_path }}
-; LFS authentication secret
 LFS_JWT_SECRET        = {{ gitea_lfs_jwt_secret }}
 {% endif %}
-
+{{ gitea_server_extra_config }}
+;
+;
+; -> https://docs.gitea.io/en-us/config-cheat-sheet/#database-database
 [database]
-; Either "mysql", "postgres", "mssql" or "sqlite3", it's your choice
 DB_TYPE  = {{ gitea_db_type }}
 HOST     = {{ gitea_db_host }}
 NAME     = {{ gitea_db_name }}
 USER     = {{ gitea_db_user }}
-; Use PASSWD = `your password` for quoting if you use special characters in the password.
 PASSWD   = {{ gitea_db_password }}
-; For Postgres, either "disable" (default), "require", "verify-ca" or "verify-full"
-; For MySQL, either "false" (default), "true", or "skip-verify"
 SSL_MODE = {{ gitea_db_ssl }}
-; For "sqlite3" and "tidb", use an absolute path when you start gitea as service
 PATH     = {{ gitea_db_path }}
 {% if gitea_log_only_warning %}
 LOG_SQL  = false
 {% endif %}
-
+{{ gitea_database_extra_config }}
+;
+;
+; -> https://docs.gitea.io/en-us/config-cheat-sheet/#indexer-indexer
 [indexer]
-; Issue indexer storage path, available when ISSUE_INDEXER_TYPE is bleve
 ISSUE_INDEXER_PATH            = {{ gitea_home }}/indexers/issues.bleve
-; Issue indexer queue, currently support: channel or levelqueue, default is levelqueue
-ISSUE_INDEXER_QUEUE_TYPE      = levelqueue
-; When ISSUE_INDEXER_QUEUE_TYPE is levelqueue, this will be the queue will be saved path,
-; default is indexers/issues.queue
 ISSUE_INDEXER_QUEUE_DIR       = {{ gitea_home }}/indexers/issues.queue
-; repo indexer by default disabled, since it uses a lot of disk space
+REPO_INDEXER_ENABLED          = {{ gitea_repo_indexer_enabled | ternary('true', 'false') }}
-REPO_INDEXER_ENABLED          = {{ gitea_repo_indexer_enabled }}
 REPO_INDEXER_PATH             = {{ gitea_home }}/indexers/repos.bleve
 REPO_INDEXER_INCLUDE          = {{ gitea_repo_indexer_include }}
 REPO_INDEXER_EXCLUDE          = {{ gitea_repo_indexer_exclude }}
 REPO_INDEXER_EXCLUDE_VENDORED = {{ gitea_repo_exclude_vendored }}
 MAX_FILE_SIZE                 = {{ gitea_repo_indexer_max_file_size }}
+{{ gitea_indexer_extra_config }}
+;
+;
+;
+
 
 [security]
 ; Whether the installer is disabled