wallet/docs/setup/core_lightning_in_debian.md

---
title:
    Core lightning in Debian
sidebar: false
...

Building lightning on Debian turned into a dead end.  I just flat could not build core-lightning on Debian, due to python incompatibilities with
the managed python environment.

Bottom line is that the great evil of python is that building installs
for python projects is a nightmare.  It has its equivalent of dll hell.

So nothing ever works on any system other than the exact system it was
built on.

The great strength of lua is that every lua program runs its own lua
interpreter with its own lua libraries.

Instead we have python version hell and pip hell.

So, docker.


# Failed attempt to us Docker lightning

The docker container as supplied instantly terminates with an error
because it expects to find  /root/.lightning/bitcoin which of course
does not exist inside the docker container, and you cannot externally
muck with the files inside a docker container, except by running
commands that the container supports.

So to run docked lightning, a whole lot of configuration information needs
to be supplied, which is nowhere explained.

You cannot give it command line parameters, so you have to set them
in environment variables, which do not seem to be documented,
and you have to mount the directories external to your
docker container

```bash
docker run -it --rm \
    --name clightning \
    -e LIGHTNINGD_NETWORK=bitcoin \
    -e LIGHTNINGD_RPC_PORT=10420 \
    -v $HOME/.lightning:/root/.lightning \
    -v $HOME/.bitcoin:/root/.bitcoin \
elementsproject/lightningd:v23.11.2-amd64 \
lightningd --network=bitcoin --log-level=debug
```
docker run -it --rm \
    --name clightning \
    -e LIGHTNINGD_NETWORK=bitcoin \
    -e LIGHTNINGD_RPC_PORT=10420 \
    -v $HOME/.lightning:/root/.lightning \
    -v $HOME/.bitcoin:/root/.bitcoin \
elementsproject/lightningd:v23.11.2-amd64 \
lightningd --network=bitcoin --log-level=debug
```

docker run -it --rm \
    --name clightning \
    -e LIGHTNINGD_NETWORK=bitcoin \
    -e LIGHTNINGD_RPC_PORT=10420 \
    -v $HOME/.lightning:/root/.lightning \
    -v $HOME/.bitcoin:/root/.bitcoin \
elementsproject/lightningd:v22.11.1 \
lightningd --help

docker run -it --rm \
    --name clightning \
    -e LIGHTNINGD_NETWORK=bitcoin \
    -e LIGHTNINGD_RPC_PORT=10420 \
elementsproject/lightningd:v22.11.1 \
lightningd --help

The docker container can do one thing only: Run lightning with no
command arguments.

Which is great if I have everything setup, but in order
to have everything setup, I need documentation and examples
which do not seem readily applicable to lightning inside
docker.  I will want to interact with my lighning that is
inside docker with lightning-cli, which lives outside
docker, and because of python install hell, I will want
to use plugins that live inside docker, with which I will
interact using a lightning-cli that lives outside docker.

But trouble is docker comes with a pile of scripts and plugins, and
the coupling between these and the docker image is going to need
a PhD in dockerology.

The docker image just dies, because it expects no end of stuff that
just is not there.


## Install docker

```bash
# remove any dead and broken obsolete dockers that might be hanging around
for pkg in docker.io docker-doc docker-compose podman-docker containerd runc; do sudo apt-get remove $pkg; done

# Add Docker's official GPG key:
sudo apt-get update
sudo apt-get install -y  pinentry-gnome3 tor parcimonie xloadimage scdaemon pinentry-doc
sudo apt-get install -y ca-certificates curl gnupg
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

# Add the repository to Apt sources:
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/debian bookworm stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
cat /etc/apt/sources.list.d/docker.list
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo usermod -aG docker ${USER}
docker run hello-world
```


## install lightning within docker

Check available images in [docker hub](https://hub.docker.com/r/elementsproject/lightningd/tags){target="_blank"}

```bash
docker pull elementsproject/lightningd:v23.11.2-amd64
docker images
```

# Failed attempt to build core lightning in Debian

## Set up a non Debian python

Core lightning requires `python` and `pip`  Debian does not like outsiders mucking with its fragile and complicated python.

So you have to set up a virtual environment in which you are free
to do what you like without affecting the rest of Debian:

The double braces `«»` mean that you do not copy the text inside
the curly braces, which is only there for example.
You have to substitute your own python version, mutas mutandis,
which you learned by typing `python3 -V`

```bash
sudo apt update
sudo apt -y full-upgrade
sudo apt install -y python3-pip
sudo apt install -y build-essential libssl-dev libffi-dev
sudo apt install -y python3-dev python3-venv
python3 -V
mkdir mypython
cd mypython
python«3.11» -m venv my_env
```

You now have your own python environment, which you activate with the command

```bash
source my_env/bin/activate
```

Within this environment, you no longer have to use python3 and pip3, nor should you use them.
You just use python and pip, which means that all those tutorials
on python projects out there on the web now work

All your python stuff that is not part of Debian managed python should be inside your `mypython` directory, and when you leave it

```bash
deactivate
```

## building core lightining

Outside your python environment:

```bash
sudo apt-get install -y \
  autoconf automake build-essential git libtool libsqlite3-dev \
  python3 python3-pip net-tools zlib1g-dev libsodium-dev gettext \
  python3-json5 python3-flask python3-gunicorn \
  cargo rustfmt protobuf-compiler
```

Then, inside your mypython directory, activate your python environment and install the python stuff

```bash
source my_env/bin/activate
pip install --upgrade pip
pip install poetry
pip install flask-cors flask_restx pyln-client flask-socketio \
gevent gevent-websocket mako
pip install -r plugins/clnrest/requirements.txt
```
The instructions on the web for ubuntu say `--user` and `pip3`, but on Debian, we accomplish the equivalent through using a virtual environment.

`--user` is Ubuntu’s way of keeping your custom python separate,
but Debian insists on a more total separation.

Which means that anything that relies heavily on custom python has
to be inside this environment, so to be on the safe side, we are
going to launch core lighting with a bash script that first goes
into this environment.

`poetry` is an enormous pile of python tools, which core lightning uses,
and outside this environment, probably will not work.

Inside your environment:

```bash
git clone https://github.com/ElementsProject/lightning.git
cd lightning
git tag
# find the most recent release version
# mutas mutandis
git checkout «v23.11.2»
./configure
make
# And then it dies
```