feat: Ansible scripts for automating the deployment of Lava Services in Docker containers.

impulse-automation/README.md

@@ -0,0 +1,11 @@
+# Ansible Automation for Lava Docker Services
+
+This repository contains Ansible playbooks and templates essential for setting up various Lava Services using Docker and Docker Compose. These tools ensure easy, scalable deployments across multiple environments adaptive to specific service requirements of the Lava ecosystem.
+
+## Directory Structure
+
+- **`/ansible/cache/`**: Contains playbooks for deploying the Lava cache service.
+- **`/ansible/provider/`**: Focuses on the Lava RPC Provider service deployment.
+- **`/ansible/node/`**: Dedicated to setting up and managing Lava nodes with a focus on ensuring optimal performance and reliability.
+
+> Each directory is equipped with its own README.md providing detailed documentation on the deployment and management processes for the respective services. Explore these directories to understand specific configurations and operational procedures related to each service.

impulse-automation/cache/README.md

@@ -0,0 +1,84 @@
+# Cache Service Deployment
+
+This `cache` directory contains Ansible playbooks and templates for deploying the configuration to set up a service based on the `lava` cache, using Docker and Docker Compose.
+
+## Requirements
+
+- **Ansible 2.9** or higher.
+- **Docker** installed on the host machine.
+- **Docker Compose** installed on the host machine.
+- **Access** to the host machine as a user with sudo privileges.
+
+## Setup
+
+1. **Clone the repository**:
+   Ensure that you have cloned this repository to your local machine or to the server where you want to run the playbook.
+
+2. **Configure Hosts**:
+   Update the `hosts` file in the `inventory` directory to match the target deployment environment's IP address or hostname.
+
+3. **Set Variables**:
+   Customize variables in `group_vars/all.yml` and `host_vars/<hostname>.yml` to match your deployment settings. These settings include the Docker image, network configurations, and resource limits.
+
+## Deployment
+
+The deployment process involves setting directly configuring Docker networks, generating necessary configuration claims, and managing Docker containers through Docker Compose.
+
+### Prepare VM on clean system
+
+If you plan to deploy on a clean Debian or Ubuntu system without an installed Docker engine, use the `prepare` tag to install additional software:
+
+```bash
+ansible-playbook main.yml --tags prepare
+```
+
+![lava_prepare_gifsicle.gif](..%2Fguides%2Flava_prepare_gifsicle.gif)
+
+### Deploying the Cache Service
+
+To deploy the cache service, run the following command:
+
+```bash
+ansible-playbook main.yml --tags deploy
+```
+
+This command executes the role that sets up directories, configures Docker Compose, and ensures that the network is ready for the service to run.
+
+> Note that by default ```anisble-playbook main.yml``` command deploys and runs the service.
+
+![lava_cache_provider_gifsicle.gif](..%2Fguides%2Flava_cache_provider_gifsicle.gif)
+
+## Managing
+
+The managing process involves such operations as: starting the service, stopping and restarting. They runs using corresponding tags.
+
+### Starting the Service
+
+To start the cache service if it is not already running, use the following command:
+
+```bash
+ansible-playbook main.yml --tags start
+```
+
+### Stopping the Service
+
+To stop the cache service, execute:
+
+```bash
+ansible-playbook main.yml --tags stop
+```
+
+This command will stop the Docker container without removing the configuration, allowing you to restart it later without reconfiguration.
+
+### Restarting the Service
+
+If you need to restart the cache service, you can use:
+
+```bash
+ansible-playbook main.yml --tags restart
+```
+
+## Configuration Files
+
+- Docker Compose Configuration: Located at `{{ project_path }}/docker-compose.yml`, it defines the service setup, including image, ports, and environment variables.
+- Environment Variables: Stored in `{{ project_path }}/cache.env`, this file includes environment-specific variables like log level and cache expiration.

impulse-automation/cache/ansible.cfg

@@ -0,0 +1,30 @@
+[defaults]
+# Defines the location of the inventory file that Ansible will use to find the host information.
+inventory = ./inventory/hosts
+
+# Path where Ansible will look for the roles.
+roles_path = roles
+
+# The number of parallel processes to use when Ansible executes tasks on multiple hosts.
+forks = 20
+
+# Disables SSH host key checking, making Ansible automatically accept unknown host keys.
+# This is useful in automated environments to avoid manual intervention.
+host_key_checking = False
+
+# Changes the default merging behavior of variables. With 'merge', hashes will be deeply merged.
+hash_behaviour = merge
+
+# Enables pipelining, which reduces the number of SSH operations required to execute a module.
+# This can result in a significant performance improvement but may not be compatible with all setups.
+pipelining = True
+
+# Specifies the SSH private key file to use for SSH authentication.
+private_key_file = ~/.ssh/id_rsa
+
+[ssh_connection]
+# SSH arguments used when connecting to hosts.
+# - ForwardAgent=yes: Allows SSH agent forwarding.
+# - ControlMaster=auto: Enables the sharing of multiple sessions over a single network connection.
+# - ControlPersist=60s: Makes the master connection stay open in the background for up to 60 seconds after the initial connection, improving subsequent connection times.
+ssh_args = -o ForwardAgent=yes -o ControlMaster=auto -o ControlPersist=60s

impulse-automation/cache/inventory/group_vars/all.yml

@@ -0,0 +1,9 @@
+# group_vars/all.yml
+---
+ansible_user: root
+ansible_port: 22
+project_name: lava
+project_type: cache
+project_unique_name: "{{ project_name }}-{{ project_type }}"
+service_path: /opt/services
+project_path: "{{ service_path }}/{{ project_unique_name }}"

impulse-automation/cache/inventory/host_vars/lava-cache-eu.yml

@@ -0,0 +1,25 @@
+# host_vars/lava-cache-eu.yml
+---
+ansible_host: xxx.xxx.xxx.xxx  # Specify your host
+network: testnet
+
+container:
+  image: svetekllc/lava  # The docker image as an example. Feel free to use your own if you want
+  tag: v2.0.1-cache
+  limits:
+    cpu: 1
+    memory: 2gb
+
+cache_config:
+  expiration: 1h0m0s      # Duration after which cached items expire and are removed
+  cache_port: 23100       # The port number on which the cache server will listen
+  log_level: info         # The verbosity level for logs
+  max_items: 500000000    # The maximum number of items the cache can store
+  metrics_port: 23101     # The port number on which the metrics service will listen
+
+cache_ports:
+  listen: "{{ cache_config.cache_port }}"
+  metrics: "{{ cache_config.metrics_port }}"
+
+networks:
+  - lava

impulse-automation/cache/inventory/hosts

@@ -0,0 +1,3 @@
+all:
+  hosts:
+    lava-cache-eu:

impulse-automation/cache/main.yml

@@ -0,0 +1,35 @@
+---
+# The main playbook for cache deployment
+- name: Cache service deployment
+  hosts: all
+  become: true
+  gather_facts: true
+  roles:
+    - role: prepare
+      tags:
+        - never
+        - prepare
+    - role: deploy
+      tags:
+        - deploy
+  tasks:
+    - name: Run the service
+      community.docker.docker_compose_v2:
+        project_src: "{{ project_path }}"
+        state: present
+      tags:
+        - start
+    - name: Stop the service
+      community.docker.docker_compose_v2:
+        project_src: "{{ project_path }}"
+        state: stopped
+      tags:
+        - never
+        - stop
+    - name: Restart the service
+      community.docker.docker_compose_v2:
+        project_src: "{{ project_path }}"
+        state: restarted
+      tags:
+        - never
+        - restart

impulse-automation/cache/roles/deploy/defaults/main.yml

@@ -0,0 +1 @@
+# roles/deploy/defaults/main.yml

impulse-automation/cache/roles/deploy/meta/main.yml

@@ -0,0 +1,19 @@
+# roles/deploy/meta/main.yml
+---
+dependencies: []
+galaxy_info:
+  author: Michael
+  description: The role for deploying the lava cache service
+  company: Impulse Expert | https://impulse.expert
+  license: GPL
+  min_ansible_version: "2.9"
+  platforms:
+    - name: Ubuntu
+      versions:
+        - xenial
+        - bionic
+        - focal
+  galaxy_tags:
+    - lava
+    - rpc
+    - docker

impulse-automation/cache/roles/deploy/tasks/main.yml

@@ -0,0 +1,23 @@
+# roles/deploy/tasks/main.yml
+---
+- name: "Create a directory for the docker-compose file"
+  ansible.builtin.file:
+    path: "{{ project_path }}"
+    state: directory
+    mode: "0755"
+
+- name: Generate the docker-compose file
+  ansible.builtin.template:
+    src: "docker-compose.yml.j2"
+    dest: "{{ project_path }}/docker-compose.yml"
+    mode: "0644"
+
+- name: Generate the cache.env file
+  ansible.builtin.template:
+    src: "cache.env.j2"
+    dest: "{{ project_path }}/cache.env"
+    mode: "0644"
+
+- name: "Create the network"
+  community.docker.docker_network:
+    name: "{{ project_name }}"

impulse-automation/cache/roles/deploy/templates/cache.env.j2

@@ -0,0 +1,17 @@
+### Cache variables ###
+
+# Duration after which cached items expire and are removed. Default is 1 hour.
+# Format is [hours]h[minutes]m[seconds]s.
+EXPIRATION="{{ cache_config.expiration }}"
+
+# The port number on which the cache server will listen. (default: 23100)
+CACHE_PORT="{{ cache_config.cache_port }}"
+
+# The verbosity level for logs. Available levels are trace, debug, info, warn, error, fatal, and panic.
+LOGLEVEL="{{ cache_config.log_level }}"
+
+# The maximum number of items the cache can store. Default is 2,147,483,648.
+MAX_ITEMS="{{ cache_config.max_items }}"
+
+# The port number on which the metrics service will listen.
+METRICS_PORT="{{ cache_config.metrics_port }}"

impulse-automation/cache/roles/deploy/templates/docker-compose.yml.j2

@@ -0,0 +1,37 @@
+---
+name: {{ project_unique_name }}
+
+services:
+  cache:
+    image: {{ container.image }}:{{ container.tag }}
+    container_name: {{ project_unique_name }}
+    labels:
+      network: "{% if network %}{{ network }}{% else %}-no_network_set{% endif %}"
+    env_file:
+      - cache.env
+    ports:
+{% for key, value in cache_ports.items() %}
+      - "{{ value }}:{{ value }}"
+{% endfor %}
+    networks:
+{% for value in networks %}
+      - {{ value }}
+{% endfor %}
+    logging:
+      driver: "json-file"
+      options:
+        max-size: "100m"
+        max-file: "1"
+    deploy:
+      resources:
+        limits:
+          cpus: "{{ container.limits.cpu }}"
+          memory: "{{ container.limits.memory }}"
+    restart: unless-stopped
+
+networks:
+{% for value in networks %}
+  {{ value }}:
+    name: {{ value }}
+    external: true
+{% endfor %}

impulse-automation/cache/roles/deploy/vars/main.yml

@@ -0,0 +1,11 @@
+# roles/deploy/vars/main.yml
+
+# In Ansible, the priority of variable values is determined by 
+# the order in which they are defined, known as variable precedence.
+# Variables defined in roles/deploy/vars/main.yml can override the values set in the inventory
+# if they are specified later in the precedence order.
+
+# Examples:
+# network: testnet
+# cache_config:
+#   cache_port: 23100

impulse-automation/cache/roles/prepare/meta/main.yml

@@ -0,0 +1,21 @@
+# roles/prepare/meta/main.yml
+---
+dependencies: []
+galaxy_info:
+  author: Michael
+  description: The role for deploying the lava cache service
+  company: Impulse Expert | https://impulse.expert
+  license: GPL
+  min_ansible_version: "2.9"
+  platforms:
+    - name: Ubuntu
+      versions:
+        - xenial
+        - bionic
+        - focal
+    - name: Debian
+      versions:
+        - buster
+        - bullseye
+        - bookworm
+