README.md 4.73 KB
Newer Older
Nikita Titov's avatar
Nikita Titov committed
1
# Using LightGBM via Docker
wxchan's avatar
wxchan committed
2

Nikita Titov's avatar
Nikita Titov committed
3
This directory contains `Dockerfile`s to make it easy to build and run LightGBM via [Docker](https://www.docker.com/).
wxchan's avatar
wxchan committed
4

5
6
These builds of LightGBM all train on the CPU. For GPU-enabled builds, see [the gpu/ directory](./gpu).

wxchan's avatar
wxchan committed
7
8
## Installing Docker

Nikita Titov's avatar
Nikita Titov committed
9
Follow the general installation instructions [on the Docker site](https://docs.docker.com/install/):
wxchan's avatar
wxchan committed
10

Nikita Titov's avatar
Nikita Titov committed
11
12
13
* [macOS](https://docs.docker.com/docker-for-mac/install/)
* [Ubuntu](https://docs.docker.com/install/linux/docker-ce/ubuntu/)
* [Windows](https://docs.docker.com/docker-for-windows/install/)
wxchan's avatar
wxchan committed
14

15
## Using CLI Version of LightGBM via Docker
wxchan's avatar
wxchan committed
16

17
Build an image with the LightGBM CLI.
wxchan's avatar
wxchan committed
18

19
```shell
20
21
22
mkdir lightgbm-docker
cd lightgbm-docker
wget https://raw.githubusercontent.com/Microsoft/LightGBM/master/docker/dockerfile-cli
23
24
25
26
docker build \
    -t lightgbm-cli \
    -f dockerfile-cli \
    .
27
28
```

29
30
Once that completes, the built image can be used to run the CLI in a container.
To try it out, run the following.
31

32
33
34
35
36
37
38
39
40
```shell
# configure the CLI
cat << EOF > train.conf
task = train
objective = binary
data = binary.train
num_trees = 10
output_model = LightGBM-CLI-model.txt
EOF
41

42
43
# get training data
curl -O https://raw.githubusercontent.com/Microsoft/LightGBM/master/examples/binary_classification/binary.train
44

45
46
47
48
49
50
51
# train, and save model to a text file
docker run \
  --rm \
  --volume "${PWD}":/opt/training \
  --workdir /opt/training \
  lightgbm-cli \
  config=train.conf
52
53
```

54
After this runs, a LightGBM model can be found at `LightGBM-CLI-model.txt`.
55

56
For more details on how to configure and use the LightGBM CLI, see https://lightgbm.readthedocs.io/en/latest/Quick-Start.html.
57

58
## Running the Python-package Container
59

60
Build an image with the LightGBM Python-package installed.
61

62
```shell
63
64
65
mkdir lightgbm-docker
cd lightgbm-docker
wget https://raw.githubusercontent.com/Microsoft/LightGBM/master/docker/dockerfile-python
66
67
68
69
docker build \
    -t lightgbm-python \
    -f dockerfile-python \
    .
70
```
wxchan's avatar
wxchan committed
71

72
73
Once that completes, the built image can be used to run LightGBM's Python-package in a container.
Run the following to produce a model using the Python-package.
74
75
76
77
78
79
80
81
82
83
84
85
86

```shell
# get training data
curl -O https://raw.githubusercontent.com/Microsoft/LightGBM/master/examples/binary_classification/binary.train

# create training script
cat << EOF > train.py
import lightgbm as lgb
import numpy as np
params = {
    "objective": "binary",
    "num_trees": 10
}
wxchan's avatar
wxchan committed
87

88
89
90
91
92
93
94
95
96
97
98
99
100
101
bst = lgb.train(
    train_set=lgb.Dataset("binary.train"),
    params=params
)
bst.save_model("LightGBM-python-model.txt")
EOF

# run training in a container
docker run \
    --rm \
    --volume "${PWD}":/opt/training \
    --workdir /opt/training \
    lightgbm-python \
    python train.py
102
```
103
104
105
106
107
108
109
110
111
112
113
114

After this runs, a LightGBM model can be found at `LightGBM-python-model.txt`.

Or run an interactive Python session in a container.

```shell
docker run \
    --rm \
    --volume "${PWD}":/opt/training \
    --workdir /opt/training \
    -it lightgbm-python \
    python
115
```
Daniel Nüst's avatar
Daniel Nüst committed
116

117
## Running the R-package Container
Daniel Nüst's avatar
Daniel Nüst committed
118

119
Build an image with the LightGBM R-package installed.
Daniel Nüst's avatar
Daniel Nüst committed
120

121
```shell
Daniel Nüst's avatar
Daniel Nüst committed
122
123
124
mkdir lightgbm-docker
cd lightgbm-docker
wget https://raw.githubusercontent.com/Microsoft/LightGBM/master/docker/dockerfile-r
125
126

docker build \
127
    -t lightgbm-r \
128
129
130
131
    -f dockerfile-r \
    .
```

132
133
Once that completes, the built image can be used to run LightGBM's R-package in a container.
Run the following to produce a model using the R-package.
Daniel Nüst's avatar
Daniel Nüst committed
134

135
136
137
```shell
# get training data
curl -O https://raw.githubusercontent.com/Microsoft/LightGBM/master/examples/binary_classification/binary.train
Daniel Nüst's avatar
Daniel Nüst committed
138

139
140
141
142
143
144
145
# create training script
cat << EOF > train.R
library(lightgbm)
params <- list(
    objective = "binary"
    , num_trees = 10L
)
Daniel Nüst's avatar
Daniel Nüst committed
146

147
148
149
150
151
152
153
154
155
156
157
158
159
160
bst <- lgb.train(
    data = lgb.Dataset("binary.train"),
    params = params
)
lgb.save(bst, "LightGBM-R-model.txt")
EOF

# run training in a container
docker run \
    --rm \
    --volume "${PWD}":/opt/training \
    --workdir /opt/training \
    lightgbm-r \
    Rscript train.R
Daniel Nüst's avatar
Daniel Nüst committed
161
162
```

163
After this runs, a LightGBM model can be found at `LightGBM-R-model.txt`.
Daniel Nüst's avatar
Daniel Nüst committed
164

165
Run the following to get an interactive R session in a container.
Daniel Nüst's avatar
Daniel Nüst committed
166

167
168
169
170
171
```shell
docker run \
    --rm \
    -it lightgbm-r \
    R
Daniel Nüst's avatar
Daniel Nüst committed
172
```
173
174
175
176
177
178
179
180
181

To use [RStudio](https://www.rstudio.com/products/rstudio/), an interactive development environment, run the following.

```shell
docker run \
    --rm \
    --env PASSWORD="lightgbm" \
    -p 8787:8787 \
    lightgbm-r
Daniel Nüst's avatar
Daniel Nüst committed
182
183
```

184
Then navigate to `localhost:8787` in your local web browser, and log in with username `rstudio` and password `lightgbm`.
Daniel Nüst's avatar
Daniel Nüst committed
185

186
To target a different R version, pass any [valid rocker/verse tag](https://hub.docker.com/r/rocker/verse/tags) to `docker build`.
Daniel Nüst's avatar
Daniel Nüst committed
187

188
For example, to test LightGBM with R 4.5:
Daniel Nüst's avatar
Daniel Nüst committed
189

190
191
```shell
docker build \
192
    -t lightgbm-r-45 \
193
    -f dockerfile-r \
194
    --build-arg R_VERSION=4.5 \
195
    .
Daniel Nüst's avatar
Daniel Nüst committed
196
```