Document how to run CodeCarbon as a service

.gitignore

@@ -8,11 +8,9 @@ __pycache__/
 *intel_power_gadget_log.csv
 *powermetrics_log.txt
 !tests/test_data/mock*
-.codecarbon.config
 
 # C extensions
 *.so
-.codecarbon.config
 
 # Distribution / packaging
 .Python
@@ -132,4 +130,5 @@ tests/test_data/rapl/*
 *.cast
 
 # credentials
-credentials.json
+credentials*
+.codecarbon.config*

codecarbon/cli/main.py

@@ -1,4 +1,5 @@
 import os
+import sys
 import time
 from pathlib import Path
 from typing import Optional
@@ -99,12 +100,14 @@ def show_config(path: Path = Path("./.codecarbon.config")) -> None:
         )
 
 
-fief = Fief(AUTH_SERVER_URL, AUTH_CLIENT_ID)
-fief_auth = FiefAuth(fief, "./credentials.json")
+def get_fief_auth():
+    fief = Fief(AUTH_SERVER_URL, AUTH_CLIENT_ID)
+    fief_auth = FiefAuth(fief, "./credentials.json")
+    return fief_auth
 
 
 def _get_access_token():
-    access_token_info = fief_auth.access_token_info()
+    access_token_info = get_fief_auth().access_token_info()
     access_token = access_token_info["access_token"]
     return access_token
 
@@ -124,7 +127,7 @@ def api_get():
 
 @codecarbon.command("login", short_help="Login to CodeCarbon")
 def login():
-    fief_auth.authorize()
+    get_fief_auth().authorize()
 
 
 def get_api_key(project_id: str):
@@ -327,7 +330,10 @@ def monitor(
     experiment_id = get_existing_local_exp_id()
     if api:
         if experiment_id is None:
-            print("ERROR: No experiment id, call 'codecarbon config' first.", err=True)
+            print(
+                "ERROR: No experiment id, call 'codecarbon config' first.",
+                file=sys.stderr,
+            )
     print("CodeCarbon is going in an infinite loop to monitor this machine.")
     with EmissionsTracker(
         measure_power_secs=measure_power_secs,

docs/edit/installation.rst

@@ -62,3 +62,115 @@ The following packages are used by the CodeCarbon package, and will be installed
 
 
 Please refer to `pyproject.toml <https://github.com/mlco2/codecarbon/blob/master/pyproject.toml>`_ for the latest list of the packages used.
+
+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=DEBUG
+    # 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/.

docs/edit/methodology.rst

@@ -120,7 +120,7 @@ If you do not want to give sudo rights to your user, then CodeCarbon will fall b
 
 - **On Linux**
 
-Tracks Intel and AMD processor energy consumption from Intel RAPL files at ``\sys\class\powercap\intel-rapl`` ( `reference <https://web.eece.maine.edu/~vweaver/projects/rapl/>`_ ).
+Tracks Intel and AMD processor energy consumption from Intel RAPL files at ``/sys/class/powercap/intel-rapl`` ( `reference <https://web.eece.maine.edu/~vweaver/projects/rapl/>`_ ).
 All CPUs listed in this directory will be tracked. `Help us improve this and make it configurable <https://github.com/mlco2/codecarbon/issues/156>`_.
 
 *Note*: The Power Consumption will be tracked only if the RAPL files exist at the above-mentioned path