Skip to content

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:

sudo useradd -r -s /bin/false codecarbon

Create a directory for the CodeCarbon service:

sudo mkdir /opt/codecarbon

Change the ownership of the directory to the user created above:

sudo chown codecarbon:codecarbon /opt/codecarbon

Create a virtual environment for CodeCarbon :

sudo apt install python3-venv
sudo -u codecarbon python3 -m venv /opt/codecarbon/.venv

Install CodeCarbon in the virtual environment:

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:

sudo -u codecarbon /opt/codecarbon/.venv/bin/codecarbon login

Create a systemd service file:

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:

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:

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:

sudo systemctl enable codecarbon
sudo systemctl start codecarbon

Check the traces of the service:

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

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:

    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:

    organization_id: your_org_id
project_id: your_project_id
experiment_id: your_experiment_id
api_key: your_api_key

  3. Run the playbook:

    ansible-playbook -i hosts tasks/main.yml