prind/docker/klipper/README.md

This Image is built and used by [prind](.).

# Klipper packaged in Docker
## What is Klipper?

>Klipper is a 3d-Printer firmware. It combines the power of a general purpose computer with one or more micro-controllers. See the features document for more information on why you should use Klipper.

_via https://www.klipper3d.org/_

## Usage
As Klipper needs access to your hosts devices, it is recommended to run it in privileged mode and mount your hosts `/dev` directory.  
It is possible to run klipper in unprivileged mode but this will break as soon as your MCU resets and gets assigned a new Device name by your hosts OS. See [this issue](https://github.com/mkuf/prind/issues/77) for reference.

### Standalone
Create a configfile `printer.cfg` and a directory `run`, then run the container.  
Point your GCODE-Sender to `klipper.tty` within the `run` directory. 

#### Run
```bash
docker run \
  --privileged \
  -v /dev:/dev \
  -v $(pwd)/run:/opt/printer_data/run \
  -v $(pwd)/printer.cfg:/opt/printer_data/config/printer.cfg \
  mkuf/klipper:latest
```

#### Compose
```yaml
services:
  klipper:
    image: mkuf/klipper:latest
    privileged: true
    volumes:
      - /dev:/dev
      - ./printer.cfg:/opt/printer_data/config/printer.cfg
      - ./run:/opt/printer_data/run
```

### With Moonraker
If you intend to use Klipper together with Moonraker, they need to share a common directory in which the socket may be located.
Further Info on how to use the Moonraker Image can be found in its [README.md](../moonraker/README.md)

Create `moonraker.conf` and `printer.cfg` as well as the directories `run` and `gcode`, then run the containers.

#### Run
```bash
docker run \
  --privileged \
  -v /dev:/dev
  -v $(pwd)/run:/opt/printer_data/run \
  -v $(pwd)/gcode:/opt/printer_data/gcodes \
  -v $(pwd)/printer.cfg:/opt/printer_data/config/printer.cfg \
  mkuf/klipper:latest

docker run \
  -v $(pwd)/run:/opt/printer_data/run \
  -v $(pwd)/gcode:/opt/printer_data/gcodes \
  -v $(pwd)/moonraker.conf:/opt/printer_data/config/moonraker.conf \
  -p 7125:7125 \
  mkuf/moonraker:latest
```

#### Compose
```yaml
services:
  klipper:
    image: mkuf/klipper:latest
    privileged: true
    volumes:
      - /dev:/dev
      - ./printer.cfg:/opt/printer_data/config/printer.cfg
      - ./run:/opt/printer_data/run
      - ./gcode:/opt/printer_data/gcodes

  moonraker:
    image: mkuf/moonraker:latest
    ports:
      - "7125:7125"
    volumes:
      - ./moonraker.conf:/opt/printer_data/config/moonraker.conf
      - ./run:/opt/printer_data/run
      - ./gcode:/opt/printer_data/gcodes
```

## Defaults
|Entity|Description|
|---|---|
|User| `klipper (1000:1000)` |
|Workdir|`/opt`|
|Entrypoint|`/opt/venv/bin/python klipper/klipper/klippy.py`|
|Cmd|`-I printer_data/run/klipper.tty -a printer_data/run/klipper.sock printer_data/config/printer.cfg`|

## Ports
none

## Volumes
|Volume|Description|
|---|---|
|`/opt/printer_data/run`| Default Location for runtime Files generated by Klipper. <br>Namely `klipper.tty`, the emulated Serial device <br>and `klipper.sock`, the unix socket that is used for communation with moonraker |
|`/opt/printer_data/config`|Config directory to host `printer.cfg`|
|`/opt/printer_data/gcodes`|Stores GCODE Files to be used by Klipper|
|`/opt/printer_data/logs`|Log directory for Klipper and Moonraker|

## Tags
|Tag|Description|Static|
|---|---|---|
|`latest`|Refers to the most recent runtime Image for klippy.|May point to a new build within 24h, depending on code changes in the upstream repository.|
|`<git description>` <br>eg: `v0.12.0-114-ga77d0790`|Refers to a specific [git description](https://git-scm.com/docs/git-describe#_examples) in the upstream repository. eg: [Klipper3d/klipper:v0.12.0-114-ga77d0790](https://github.com/Klipper3d/klipper/commit/a77d07907fdfcd76f7175231caee170db205ff04)|Yes|
|`*-tools`|Refers to Debian Image containing all Tools necessary to Build the Microcontroller code for Klipper|Yes|
|`*-hostmcu`|Refers to the runtime Image for klipper_mcu.|Yes|

## Targets
|Target|Description|Pushed|
|---|---|---|
|`build`|Pull Upstream Codebase and build python venv|No|
|`build-simulavr`|Based on `mcu`: Pull and Build simulavr for klipper. Used for testing without Hardware.|No|
|`build-hostmcu`|Based on `mcu`: Build the klipper_mcu binary|No|
|`run`|Default runtime Image for klippy|Yes|
|`tools`|Build Tools for MCU code compilation|Yes|
|`hostmcu`|Runtime Image for the klipper_mcu binary|Yes|

## Healthcheck
`/opt/health.py` is available to check the health of the container.  

> Be aware that enabling health checks in docker may increase CPU usage drastically.  
> In tests, cpu usage of the container was doubled when executing the healtch check every 30s and increased sixfold when executing every 5s.  
> This may lead to resource shortages on low powered host and unwanted behaviour  

The script does the following:
* queries klippers `info` endpoint via its unix socket
* Checks if state is `ready`
* If one of the above requirements is not `ready`, the script exits with a failure state to indicate the container is unhealthy

Compose example:
```yaml
services:
  klipper:
    healthcheck:
      test: ["python3", "/opt/health.py"]
      interval: 30s
```