diff --git a/docs/guides/developer/Role_Creation.md b/docs/guides/developer/Role_Creation.md new file mode 100644 index 00000000..c34be5e3 --- /dev/null +++ b/docs/guides/developer/Role_Creation.md @@ -0,0 +1,185 @@ +### *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. + +```yaml +defaults_applications: + + ## My Service Configuration + my_service: + version: "latest" # Version of the service + matomo_tracking_enabled: true # Enable Matomo tracking for analytics + css_enabled: true # Enable or disable global CSS styling + landingpage_iframe_enabled: false # Allow embedding the landing page in an iframe (if true) +``` + +--- + +### **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`. + +```yaml +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. + +```yaml +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`: + ```yaml + --- + # 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`: + ```yaml + 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`: + ```yaml + application_id: "my_service" + ``` + +5. **`meta/main.yml`**: + - Add metadata for your new role. + + Example `meta/main.yml`: + ```yaml + 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. \ No newline at end of file