diff --git a/README.md b/README.md index 266db84..a1430fd 100644 --- a/README.md +++ b/README.md @@ -7,6 +7,7 @@ Roles for deploying matrix infrastructure using ansible. ## Roles - [`cinny`](roles/cinny/README.md): [Cinny](https://cinny.in/) Web Client +- [`element`](roles/element/README.md): [Element](https://element.io/) Web Client ## License diff --git a/playbooks/element.yml b/playbooks/element.yml new file mode 100644 index 0000000..c4381a5 --- /dev/null +++ b/playbooks/element.yml @@ -0,0 +1,6 @@ +--- +- name: Deploy and configure element + hosts: "{{ element_hosts | default('element') }}" + become: "{{ element_become | default(true) }}" + roles: + - role: finallycoffee.matrix.element diff --git a/roles/element/README.md b/roles/element/README.md new file mode 100644 index 0000000..9cfadf0 --- /dev/null +++ b/roles/element/README.md @@ -0,0 +1,24 @@ +# `finallycoffee.matrix.element` ansible role + +## Deployment method + +Deploy the [element web-app](https://element.io/) +using the following supported methods by setting `element_deployment_method` to it: + +- [`docker` (docs)](docs/docker.md) (default) + +Planned deployment methods: + +- `podman` +- `tarball` +- `nginx` +- `apache2` + +## Configuration + +Configure your element web-app instance by setting `element_config` directly +or use flattened config keys with the `element_config_` prefix. + +For all available keys see +[the upstream configuration manual](https://github.com/element-hq/element-web/blob/develop/docs/config.md) +or [the role defaults in `defaults/config.yml`](defaults/config.yml). diff --git a/roles/element/defaults/main/config.yml b/roles/element/defaults/main/config.yml new file mode 100644 index 0000000..9b80e43 --- /dev/null +++ b/roles/element/defaults/main/config.yml @@ -0,0 +1,10 @@ +--- +element_config_complete: >- + {{ element_config | default({}) + | combine(element_default_config | default({})) }} +element_config: {} +element_default_config: + default_server_name: "{{ element_config_default_server_name }}" + show_labs_settings: "{{ element_config_show_labs_settings }}" +element_config_default_server_name: "matrix.org" +element_config_show_labs_settings: false diff --git a/roles/element/defaults/main/container.yml b/roles/element/defaults/main/container.yml new file mode 100644 index 0000000..04677c1 --- /dev/null +++ b/roles/element/defaults/main/container.yml @@ -0,0 +1,25 @@ +--- +element_container_image: >- + {{ + element_container_image_registry + '/' + + ((element_container_image_namespace + '/') + if element_container_image_namespace | default(false, true) else '') + + element_container_image_name + ':' + + (element_container_image_tag | default('v' + element_version, true)) + }} +element_container_image_registry: "docker.io" +element_container_image_namespace: "vectorim" +element_container_image_name: "element-web" +element_container_image_tag: ~ +element_container_name: "element-web" +element_container_restart_policy: >- + {{ (element_deployment_method == 'docker') + | ternary('unless-stopped', + (element_deployment_method == 'podman' | + ternary('on-failure', 'always')) + }} +element_container_full_volumes: >- + {{ element_container_default_volumes + + element_container_volumes | default([]) }} +element_container_default_volumes: + - "{{ element_config_file }}:/app/config.json:ro" diff --git a/roles/element/defaults/main/main.yml b/roles/element/defaults/main/main.yml new file mode 100644 index 0000000..2efe289 --- /dev/null +++ b/roles/element/defaults/main/main.yml @@ -0,0 +1,18 @@ +--- +element_user: element +element_state: "present" +element_version: "1.11.77" +element_deployment_method: "docker" + +element_base_path: "/opt/element" +element_source_path: "{{ element_base_path }}/src" +element_dist_path: "{{ element_source_path }}/dist" +element_config_path: "{{ element_base_path }}/config" +element_config_file: "{{ element_config_path }}/config.json" + +element_host_uid: >- + {{ element_user_info is defined + | ternary(element_user_info.uid, element_user) }} +element_host_gid: >- + {{ element_user_info is defined + | ternary(element_user_info.group, element_user) }} diff --git a/roles/element/docs/docker.md b/roles/element/docs/docker.md new file mode 100644 index 0000000..cd81052 --- /dev/null +++ b/roles/element/docs/docker.md @@ -0,0 +1,33 @@ +# `element` deployment using `docker` + +> [!NOTE] +> Needs the python library `docker` on the `ansible_host`. + +## Configuration + +The following options to the +[`docker_container` module](https://docs.ansible.com/ansible/latest/collections/community/docker/docker_container_module.html) +are available under the `element_container_` prefix: + +- `env` +- `ports` +- `labels` +- `networks` +- `etc_hosts` +- `purge_networks` + +The following variables are pre-populated by the role, so override them with care: + +- `name` +- `image` +- `user` +- `volumes` +- `restart_policy` + +## Pulling from a self-hosted container registry + +Set `element_container_image_registry` to use a self-hosted docker registry / mirror / cache. + +If you need to authenticate to your registry and are not yet logged in, set `element_container_image_registry_{username,password}` and the role will attempt to log in. + +Set `element_container_image_registry_reauthorize` to `true` if you want to force a reauthorization at the registry. diff --git a/roles/element/tasks/configure.yml b/roles/element/tasks/configure.yml new file mode 100644 index 0000000..bf1a579 --- /dev/null +++ b/roles/element/tasks/configure.yml @@ -0,0 +1,35 @@ +--- +- name: Ensure element user '{{ element_user }}' is {{ element_state }} + ansible.builtin.user: + name: "{{ element_user }}" + system: "{{ element_user_system | default(true, true) }}" + create_home: "{{ element_user_create_home | default(false, true) }}" + state: "{{ element_state }}" + register: element_user_info + +- name: Ensure host paths are {{ element_state }} + ansible.builtin.file: + name: "{{ path.name }}" + state: "{{ (element_state == 'present') | ternary('directory', 'absent') }}" + owner: "{{ path.owner | default(element_host_uid) }}" + group: "{{ path.group | default(element_host_gid) }}" + mode: "{{ path.mode | default('0750') }}" + loop_control: + loop_var: path + label: "{{ path.name }}" + loop: + - name: "{{ element_base_path }}" + mode: '0755' + - name: "{{ element_config_path }}" + mode: '0755' + - name: "{{ element_source_path }}" + mode: '0750' + +- name: Ensure config file is {{ element_state }} + ansible.builtin.copy: + content: "{{ element_config | to_nice_json }}" + dest: "{{ element_config_file }}" + owner: "{{ element_host_uid }}" + group: "{{ element_host_gid }}" + mode: "{{ element_config_file_mode | default('0664') }}" + when: element_state == 'present' diff --git a/roles/element/tasks/deploy-docker.yml b/roles/element/tasks/deploy-docker.yml new file mode 100644 index 0000000..bfc8cd1 --- /dev/null +++ b/roles/element/tasks/deploy-docker.yml @@ -0,0 +1,33 @@ +--- +- name: Ensure docker client is logged {{ (element_state == 'present') | ternary('in', 'out') }} + community.docker.docker_login: + registry_url: "{{ element_container_image_registry }}" + username: "{{ element_container_image_registry_username }}" + password: "{{ element_container_image_registry_password }}" + reauthorize: "{{ element_container_image_registry_reauthorize | default(omit, true) }}" + state: "{{ element_state }}" + when: + - element_container_image_registry_username | default(false, true) + - element_container_image_registry_password | default(false, true) + +- name: Ensure container image '{{ element_container_image }}' is {{ element_state }} locally + community.docker.docker_image: + name: "{{ element_container_image }}" + state: "{{ element_state }}" + source: "{{ element_container_source }}" + force_source: "{{ element_container_image_tag | default(false, true) }}" + +- name: Ensure container '{{ element_container_name }}' is {{ element_state }} + community.docker.docker_container: + name: "{{ element_container_name }}" + image: "{{ element_container_image }}" + state: "{{ (element_state == 'present') | ternary('started', 'absent') }}" + env: "{{ element_container_env | default(omit) }}" + user: "{{ element_container_user }}" + ports: "{{ element_container_ports | default(omit) }}" + labels: "{{ element_container_labels | default(omit) }}" + volumes: "{{ element_container_full_volumes }}" + networks: "{{ element_container_networks | default(omit) }}" + etc_hosts: "{{ element_container_etc_hosts | default(omit) }}" + restart_policy: "{{ element_container_restart_policy }}" + purge_networks: "{{ element_container_purge_networks | default(omit) }}" diff --git a/roles/element/tasks/main.yml b/roles/element/tasks/main.yml new file mode 100644 index 0000000..2e3a605 --- /dev/null +++ b/roles/element/tasks/main.yml @@ -0,0 +1,20 @@ +--- +- name: Check if state is valid + ansible.builtin.fail: + msg: "Unknown state '{{ element_state }}'. Valid states are {{ element_states | join(', ') }}" + when: element_state not in element_states + +- name: Check if deployment method is supported + ansible.builtin.fail: + msg: >- + Deployment method '{{ element_deployment_method }}' is not supported! + Supported are: {{ element_deployment_methods | join(', ') }} + when: element_deployment_method not in element_deployment_methods + +- name: Include base configuration + ansible.builtin.include_tasks: + file: configure.yml + +- name: Deploy using {{ element_deployment_method }} + ansible.builtin.include_tasks: + file: "deploy-{{ element_deployment_method }}.yml" diff --git a/roles/element/vars/main.yml b/roles/element/vars/main.yml new file mode 100644 index 0000000..bcb8394 --- /dev/null +++ b/roles/element/vars/main.yml @@ -0,0 +1,7 @@ +--- +element_state: + - present + - absent + +element_deployment_methods: + - docker