Ansible Playbook

CONTRIBUTING.md

@@ -338,7 +338,7 @@ Dependencies are defined in different places:
 No software is complete without great documentation!
 To make generating documentation easier, we use [`sphinx` package](https://www.sphinx-doc.org/en/master/usage/installation.html#installation-from-pypi).
 
-In order to make changes, edit the `.rst` files that are in the `/docs/edit` folder, and then run:
+In order to make changes, edit the `.rst` files that are in the `/docs/edit` folder, and then run in root folder:
 
 ```
 hatch run docs:build

deploy/ansible/codecarbon_cli_as_a_service/hosts

@@ -0,0 +1 @@
+yourservername.yourdomain.com   hostname=yourservername ansible_user=root ansible_ssh_private_key_file=~/.ssh/id_ed25519

deploy/ansible/codecarbon_cli_as_a_service/tasks/install_codecarbon.yml

@@ -0,0 +1,51 @@
+---
+- name: Install CodeCarbon
+  hosts: all
+  vars_files:
+    - "../vars/main.yml"
+  become: true
+  become_method: sudo
+
+  tasks:
+  - name: Create CodeCarbon group
+    group:
+      name: "{{ codecarbon_group }}"
+      system: yes
+      state: present
+  - name: Create CodeCarbon user
+    user:
+      name: "{{ codecarbon_user }}"
+      group: "{{ codecarbon_group }}"
+      system: yes
+      shell: /bin/false
+      create_home: no
+      state: present
+  - name: Create CodeCarbon directory
+    file:
+       path: "{{ codecarbon_home }}"
+       state: directory
+       owner: "{{ codecarbon_user }}"
+       group: "{{ codecarbon_group }}"
+       mode: '0755'
+  - name: Install Python virtual environment package
+    apt:
+       name: python3-venv
+       state: present
+  - name: Create Python virtual environment
+    command:
+       cmd: "python3 -m venv {{ codecarbon_venv }}"
+       creates: "{{ codecarbon_venv }}"
+    become_user: "{{ codecarbon_user }}"
+  - name: Install CodeCarbon package
+    pip:
+       name: codecarbon
+       virtualenv: "{{ codecarbon_venv }}"
+    become_user: "{{ codecarbon_user }}"
+  - name: Create CodeCarbon configuration file
+    template:
+       src: ../templates/codecarbon.config.j2
+       dest: "{{ codecarbon_home }}/.codecarbon.config"
+       owner: "{{ codecarbon_user }}"
+       group: "{{ codecarbon_group }}"
+       mode: '0600'
+

deploy/ansible/codecarbon_cli_as_a_service/tasks/main.yml

@@ -0,0 +1,8 @@
+---
+# Tasks file to install CodeCarbon CLI as a service
+
+- import_playbook: install_codecarbon.yml
+
+- import_playbook: systemd_service.yml
+
+- import_playbook: rapl.yml

deploy/ansible/codecarbon_cli_as_a_service/tasks/rapl.yml

@@ -0,0 +1,46 @@
+---
+- name: Allow CodeCarbon to read RAPL files
+  hosts: all
+  vars_files:
+    - "../vars/main.yml"
+  become: true
+  become_method: sudo
+
+  tasks:
+  - name: Set RAPL directory permissions
+    shell: |
+        chmod -R g+r {{ rapl_base_path }}
+        chown -R root:{{ codecarbon_group }} {{ rapl_base_path }}
+    ignore_errors: yes  # In case RAPL is not available
+  # This does not work because there is loop in folder symlink
+  # - name: Set RAPL directory permissions
+  #   file:
+  #     path: "{{ rapl_base_path }}"
+  #     state: directory
+  #     owner: root
+  #     group: "{{ codecarbon_group }}"
+  #     mode: "g+r"
+  #     recurse: yes
+  #   ignore_errors: yes  # In case RAPL is not available
+  - name: Install sysfsutils
+    apt:
+       name: sysfsutils
+       state: present
+  - name: Find all RAPL energy_uj files
+    find:
+       paths: "{{ rapl_base_path }}"
+       patterns: 
+         - "energy_uj"
+         - "name"
+       recurse: yes
+    register: rapl_files
+  - name: Configure sysfs for RAPL permissions
+    blockinfile:
+       path: /etc/sysfs.conf
+       create: yes
+       block: |
+         {% for file in rapl_files.files %}
+         mode {{ file.path | replace('/sys/','class/') }} = 0440
+         owner {{ file.path | replace('/sys/','class/') }} = root:{{ codecarbon_group }}
+         {% endfor %}
+

deploy/ansible/codecarbon_cli_as_a_service/tasks/systemd_service.yml

@@ -0,0 +1,21 @@
+---
+- name: Install Systemd service for CodeCarbon
+  hosts: all
+  vars_files:
+    - "../vars/main.yml"
+  become: true
+  become_method: sudo
+
+  tasks:
+  - name: Create systemd service file
+    template:
+       src: ../templates/systemd_service.j2
+       dest: /etc/systemd/system/codecarbon.service
+       mode: '0644'
+
+  - name: Enable and start CodeCarbon service
+    systemd:
+       name: codecarbon
+       enabled: yes
+       state: started
+       daemon_reload: yes

deploy/ansible/codecarbon_cli_as_a_service/templates/codecarbon.config.j2

@@ -0,0 +1,12 @@
+[codecarbon]
+api_endpoint = https://api.codecarbon.io
+organization_id = {{ organization_id }}
+project_id = {{ project_id }}
+experiment_id = {{ experiment_id }}
+api_key = {{ api_key }}
+# Verbose logging
+log_level=WARNING
+# Measure power every 30 seconds
+measure_power_secs=30
+# Send measure to API every 5 minutes (10*30 seconds)
+api_call_interval=10

deploy/ansible/codecarbon_cli_as_a_service/templates/systemd_service.j2

@@ -0,0 +1,13 @@
+[Unit]
+Description=CodeCarbon service
+After=network.target
+
+[Service]
+User={{ codecarbon_user }}
+Group={{ codecarbon_group }}
+WorkingDirectory={{ codecarbon_home }}
+ExecStart={{ codecarbon_venv }}/bin/codecarbon monitor
+Restart=always
+
+[Install]
+WantedBy=multi-user.target

deploy/ansible/codecarbon_cli_as_a_service/vars/main.yml

@@ -0,0 +1,16 @@
+---
+# RAPL base path
+rapl_base_path: /sys/class/powercap/intel-rapl
+
+# CodeCarbon configuration
+codecarbon_user: codecarbon
+codecarbon_group: codecarbon
+codecarbon_home: /opt/codecarbon
+codecarbon_venv: "{{ codecarbon_home }}/venv"
+
+# Dashboard configuration
+api_endpoint: https://api.codecarbon.io
+organization_id: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+project_id: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+experiment_id: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+api_key: xxx_xxxxxxxx_xxxxxxxxxxxx

docs/edit/advanced_installation.rst

@@ -0,0 +1,185 @@
+Advanced Installation
+=====================
+
+Install CodeCarbon as a Linux service
+`````````````````````````````````````
+
+To install CodeCarbon as a Linux service, follow the instructions below. It works on Ubuntu or other Debian-based systems using systemd.
+
+Create a dedicated user:
+
+.. code-block::  bash
+
+    sudo useradd -r -s /bin/false codecarbon
+
+Create a directory for the CodeCarbon service:
+
+.. code-block::  bash
+
+    sudo mkdir /opt/codecarbon
+
+Change the ownership of the directory to the user created above:
+
+.. code-block::  bash
+
+    sudo chown codecarbon:codecarbon /opt/codecarbon
+
+Create a virtual environment for CodeCarbon :
+
+.. code-block::  bash
+
+    sudo apt install python3-venv
+    sudo -u codecarbon python3 -m venv /opt/codecarbon/.venv
+
+Install CodeCarbon in the virtual environment:
+
+.. code-block::  bash
+
+    sudo -u codecarbon /opt/codecarbon/.venv/bin/pip install codecarbon
+
+Go to https://dashboard.codecarbon.io/ and create an account to get your API key.
+
+Configure CodeCarbon:
+
+.. code-block::  bash
+
+    sudo -u codecarbon /opt/codecarbon/.venv/bin/codecarbon login
+
+Create a systemd service file:
+
+.. code-block::  bash
+
+    sudo tee /etc/systemd/system/codecarbon.service <<EOF
+    [Unit]
+    Description=CodeCarbon service
+    After=network.target
+
+    [Service]
+    User=codecarbon
+    Group=codecarbon
+    WorkingDirectory=/opt/codecarbon
+    ExecStart=/opt/codecarbon/.venv/bin/codecarbon monitor
+    Restart=always
+
+    [Install]
+    WantedBy=multi-user.target
+    EOF
+
+Give permissions to the ``codecarbon`` group to read the RAPL (Running Average Power Limit) information:
+
+.. code-block::  bash
+
+    sudo chown -R root:codecarbon /sys/class/powercap/intel-rapl/*
+    sudo chmod g+r -R /sys/class/powercap/intel-rapl/*
+
+    sudo apt install sysfsutils
+    echo "mode class/powercap/intel-rapl:0/energy_uj = 0440" >> /etc/sysfs.conf
+    echo "owner class/powercap/intel-rapl:0/energy_uj = root:codecarbon" >> /etc/sysfs.conf
+
+Create the configuration file for CodeCarbon:
+
+.. code-block::  bash
+
+    sudo tee /opt/codecarbon/.codecarbon.config <<EOF
+    [codecarbon]
+    api_endpoint = https://api.codecarbon.io
+    organization_id = <organization_id>
+    project_id = <project_id>
+    experiment_id = <experiment_id>
+    api_key = <api_key>
+    # Verbose logging
+    log_level=WARNING
+    # Measure power every 30 seconds
+    measure_power_secs=30
+    # Send measure to API every 5 minutes (10*30 seconds)
+    api_call_interval=10
+    EOF
+
+Enable and start the service:
+
+.. code-block::  bash
+
+    sudo systemctl enable codecarbon
+    sudo systemctl start codecarbon
+
+Check the traces of the service:
+
+.. code-block::  bash
+
+    journalctl -u codecarbon
+
+
+You are done, CodeCarbon is now running as a service on your machine.
+
+Wait 5 minutes for the first measure to be send to the dashboard at https://dashboard.codecarbon.io/.
+
+
+Deploy CodeCarbon CLI as a Service using Ansible
+````````````````````````````````````````````````
+
+This section describes how to deploy CodeCarbon as a system service using Ansible automation.
+
+It automate the manual installation done in the previous chapter.
+
+What the Playbook Does
+--------------------
+The Ansible playbook automates the following tasks:
+
+* Creates a dedicated system user and group for CodeCarbon
+* Sets up a Python virtual environment
+* Installs CodeCarbon package
+* Configures RAPL permissions for power measurements
+* Creates and configures the systemd service
+* Sets up the CodeCarbon configuration file
+* Starts and enables the service
+
+Prerequisites
+------------
+* Ansible installed on your machine
+* Debian-based target system(s)
+* SSH access to target system(s)
+* CodeCarbon API credentials from the dashboard
+
+Directory Structure
+-----------------
+.. code-block:: text
+
+    codecarbon/deploy/ansible/codecarbon_cli_as_a_service/
+    ├── hosts
+    ├── tasks
+    │   ├── install_codecarbon.yml
+    │   ├── main.yml
+    │   ├── rapl.yml
+    │   └── systemd_service.yml
+    ├── templates
+    │   ├── codecarbon.config.j2
+    │   └── systemd_service.j2
+    └── vars
+        └── main.yml
+
+Quick Start
+----------
+
+1. Set the the target to install in ``hosts``:
+
+   .. code-block:: txt
+
+       yourservername.yourdomain.com   hostname=yourservername ansible_user=root ansible_ssh_private_key_file=~/.ssh/id_ed25519
+
+2. Update the variables in ``vars/main.yml`` with your configuration:
+
+   .. code-block:: yaml
+
+       organization_id: your_org_id
+       project_id: your_project_id
+       experiment_id: your_experiment_id
+       api_key: your_api_key
+
+
+3. Run the playbook:
+
+   .. code-block:: bash
+
+       ansible-playbook -i hosts tasks/main.yml
+
+

docs/edit/api.rst

@@ -5,7 +5,7 @@ CodeCarbon API
 
 
 CodeCarbon API
-~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~
 
 .. warning::
     This mode use the CodeCarbon API to upload the timeseries of your emissions on a central server. All data will be public!

docs/edit/index.rst

@@ -29,6 +29,7 @@ CodeCarbon
    parameters
    examples
    comet
+   advanced_installation
 
 .. toctree::
    :caption: Logging