computer-playbook/docs/guides/developer/Role_Creation.md

*Guide to Create a New Docker Role for CyMaIS

This guide will walk you through the steps to add a new Docker role for a service (in this case, my_service) in CyMaIS. We will cover where to add the application settings, domain, and other required configuration to ensure that your new service is correctly integrated into the CyMaIS environment.

---

1. Define the Application Configuration in group_vars/all/07_applications.yml

First, you'll need to add the default configuration for your new service under the defaults_applications section in group_vars/all/07_applications.yml.

Steps:

• Open group_vars/all/07_applications.yml
• Add the configuration for my_service under the defaults_applications section.

defaults_applications:

  ## My Service Configuration
  my_service:
    version: "latest"
    features:                               # Version of the service
      matomo:     true                      # Enable Matomo tracking for analytics
      css:        true                      # Enable or disable global CSS styling
      iframe:     false                     # Allow embedding the landing page in an iframe (if true)
      database:   true                      # Enable central database integration
      ldap:       true                      # Enable ldap integration
      oauth2:     true                      # Enable oauth2 proxy
      oidc:       true                      # Enable oidc

---

2. Add the Domain for my_service in group_vars/all/03_domains.yml

Next, define the domain for your service in the group_vars/all/03_domains.yml file. The domain should be dynamic, using the {{ primary_domain }} placeholder, which will automatically resolve to the correct domain based on the primary domain used for your environment.

Steps:

• Open group_vars/all/03_domains.yml
• Add the domain for my_service.

defaults_domains:
  # Other services...
  my_service:            "slides.{{ primary_domain }}"     # Domain for the new service

---

3. Set the Application ID in vars/main.yml

In the vars/main.yml file, set the application_id to my_service. This step is essential as it allows CyMaIS to correctly reference and configure the new service when deploying it via Docker.

Steps:

• Open vars/main.yml
• Add the application_id for the new service.

application_id: "my_service"  # Set the application ID for the service

---

4. Create the Docker Role for the New Service

Now that you have defined the application settings, domain, and application ID, you need to create a Docker role that will build and run the containerized version of my_service.

Steps:

• Create a new directory under the roles directory, e.g., roles/docker-my_service.
• Inside the docker-my_service role, create the following files:

1. README.md:

   • Provide documentation on the new service and how it works within CyMaIS.

2. tasks/main.yml:

   • Define the tasks for building and running the Docker container for my_service.

   Example tasks/main.yml:

   ---
   # Docker Routines for my_service
   - name: "include docker-compose role"
     include_role:
       name: docker-compose
   
   - name: install cymais-my_service
     command:
       cmd: "pkgmgr install cymais-my_service --clone-mode https"
     notify: docker compose project build and setup
   
   - name: Get path of cymais-my_service using pkgmgr
     command: pkgmgr path cymais-my_service
     register: path_cymais_my_service_output
   
   - name: "include role nginx-domain-setup for {{ application_id }}"
     include_role:
       name: nginx-domain-setup
     vars:
       domain: "{{ domains[application_id] }}"
       http_port: "{{ ports.localhost.http[application_id] }}"
   
   - name: "copy docker-compose.yml and env file"
     include_tasks: copy-docker-compose-and-env.yml
   

3. docker-compose.yml.j2:

   • Define the docker-compose.yml template for building and running the Docker container for the new service.

   Example docker-compose.yml.j2:

   services:
     my_service:
       build:
         context: {{ path_cymais_my_service_output.stdout }}
         dockerfile: {{ path_cymais_my_service_output.stdout }}/Dockerfile
       ports:
         - "127.0.0.1:{{ ports.localhost.http[application_id] }}:5000"
       healthcheck:
         test: ["CMD", "curl", "-f", "http://127.0.0.1:5000"]
         interval: 1m
         timeout: 10s
         retries: 3
       volumes:
         - {{ path_cymais_my_service_output.stdout }}:/app
         - {{ path_cymais_output.stdout }}:/source
   

4. vars/main.yml:

   • Define any specific variables for my_service.

   Example vars/main.yml:

   application_id: "my_service"
   

5. meta/main.yml:

   • Add metadata for your new role.

   Example meta/main.yml:

   galaxy_info:
     author: "Your Name"
     description: "Docker role to deploy and manage my_service within CyMaIS."
     license: "CyMaIS NonCommercial License (CNCL)"
     company: "Your Company"
     min_ansible_version: "2.9"
     platforms:
       - name: Docker
         versions:
           - all
       - name: Linux
         versions:
           - all
     repository: "https://github.com/yourrepo/my_service"
     documentation: "https://yourdocumentationlink"
   

---

5. Test the Configuration

Once you have defined the Docker role, configuration settings, and other necessary files, it is essential to test your changes:

Steps:

• Run the Ansible playbook for deploying your new service.
• Check if my_service is correctly deployed and if the domain is resolving as expected.
• Verify that the application is accessible via the assigned port (e.g., http://slides.{{ primary_domain }}:5000).

---

6. Additional Steps for Integration

• You can add additional configurations or adjust existing settings based on the requirements for my_service. For instance:
  • Modify the health check settings in the docker-compose.yml template.
  • Update Nginx or other web servers to properly route traffic to your new service.

---

Conclusion

By following this guide, you have successfully added a new Dockerized service (my_service) to the CyMaIS platform. You have:

• Configured the service settings in group_vars/all/07_applications.yml
• Added the domain for the service in group_vars/all/03_domains.yml
• Set the application_id in vars/main.yml
• Created the necessary Docker role for managing my_service.

This process allows you to extend the functionality of CyMaIS with new services while maintaining a consistent and reproducible deployment workflow.

---

For any further details or troubleshooting, please consult the official CyMaIS documentation or reach out to the CyMaIS community for assistance.