Skip to content

Commit 94d0ef8

Browse files
author
Dave Conway-Jones
committed
overhaul docker to trim size a bit and reorder
1 parent 97874c6 commit 94d0ef8

File tree

1 file changed

+86
-108
lines changed

1 file changed

+86
-108
lines changed

‎docs/getting-started/docker.md

+86-108
Original file line numberDiff line numberDiff line change
@@ -10,22 +10,23 @@ redirect_from:
1010
This guide assumes you have some basic familiarity with Docker and the
1111
[Docker Command Line](https://docs.docker.com/engine/reference/commandline/cli/). It describes some of the many ways Node-RED can be run under Docker and has support for multiple architectures (amd64, arm32v6, arm32v7, arm64v8 and s390x).
1212

13-
As of Node-RED 1.0 this project provides the build for the `nodered/node-red` container on [Docker Hub](https://hub.docker.com/r/nodered/node-red/). Note: the name has changed to nodered/node-red.
13+
As of Node-RED 1.0 the repository on [Docker Hub](https://hub.docker.com/r/nodered/node-red/)
14+
was renamed to `nodered/node-red`.
1415

1516
Previous 0.20.x versions are still available at https://hub.docker.com/r/nodered/node-red-docker.
1617

1718
### Quick Start
1819
To run in Docker in its simplest form just run:
1920

20-
docker run -it -p 1880:1880 --name mynodered nodered/node-red
21+
docker run -it -p 1880:1880 --name mynodered nodered/node-red
2122

2223
Let's dissect that command:
2324

24-
docker run - run this container... initially building locally if necessary
25-
-it - attach a terminal session so we can see what is going on
26-
-p 1880:1880 - connect local port 1880 to the exposed internal port 1880
27-
--name mynodered - give this machine a friendly local name
28-
nodered/node-red - the image to base it on
25+
docker run - run this container... initially building locally if necessary
26+
-it - attach a terminal session so we can see what is going on
27+
-p 1880:1880 - connect local port 1880 to the exposed internal port 1880
28+
--name mynodered - give this machine a friendly local name
29+
nodered/node-red - the image to base it on
2930

3031

3132
Running that command should give a terminal window with a running instance of Node-RED.
@@ -67,46 +68,24 @@ You can then browse to `http://{host-ip}:1880` to get the familiar Node-RED desk
6768

6869
The advantage of doing this is that by giving it a name (mynodered) we can manipulate it
6970
more easily, and by fixing the host port we know we are on familiar ground.
70-
Of course this does mean we can only run one instance at a time... but one step at a time folks...
71-
72-
**Note**: Currently there is a bug in Docker's architecture detection that fails for Arm6 CPU - eg Raspberry Pi Zero or 1. For these devices you currently need to specify the full build label, for example:
73-
```
74-
docker run -it -p 1880:1880 --name mynodered nodered/node-red:1.0.2-10-minimal-arm32v6
75-
```
71+
Of course this does mean we can only run one instance at a time... but one step at a time folks.
7672

7773
If we are happy with what we see, we can detach the terminal with `Ctrl-p` `Ctrl-q` - the
7874
container will keep running in the background.
7975

8076
To reattach to the terminal (to see logging) run:
8177

82-
$ docker attach mynodered
78+
docker attach mynodered
8379

8480
If you need to restart the container (e.g. after a reboot or restart of the Docker daemon):
8581

86-
$ docker start mynodered
82+
docker start mynodered
8783

8884
and stop it again when required:
8985

90-
$ docker stop mynodered
86+
docker stop mynodered
9187

9288
### Image Variations
93-
The Node-RED images come in different variations and are supported by manifest lists (auto-detect architecture).
94-
This makes it more easy to deploy in a multi architecture Docker environment. E.g. a Docker Swarm with mix of Raspberry Pi's and amd64 nodes.
95-
96-
The tag naming convention is `<node-red-version>-<node-version>-<image-type>-<architecture>`, where:
97-
- `<node-red-version>` is the Node-RED version.
98-
- `<node-version>` is the Node JS version.
99-
- `<image-type>` is type of image and is optional, can be either _none_ or minimal.
100-
- _none_ : is the default and has Python 2 & Python 3 + devtools installed
101-
- minimal : has no Python installed and no devtools installed
102-
- `<architecture>` is the architecture of the Docker host system, can be either amd64, arm32v6, arm32v7, arm64, or s390x
103-
104-
The minimal versions (without python and build tools) are not able to install nodes that require any locally compiled native code.
105-
106-
For example - to run the latest minimal version, you would run
107-
```
108-
docker run -it -p 1880:1880 --name mynodered nodered/node-red:latest-minimal
109-
```
11089

11190
The Node-RED images are based on [official Node JS Alpine Linux](https://hub.docker.com/_/node/) images to keep them as small as possible.
11291
Using Alpine Linux reduces the built image size, but removes standard dependencies that are required for native module compilation. If you want to add dependencies with native dependencies, extend the Node-RED image with the missing packages on running containers or build new images see [docker-custom](docker-custom/README.md).
@@ -118,38 +97,15 @@ For example: suppose you are running on a Raspberry PI 3B, which has arm32v7 as
11897
docker run -it -p 1880:1880 --name mynodered nodered/node-red:latest
11998
```
12099

121-
The same command can be used for running on an amd64 system, since docker discovers its running on a amd64 host and pulls the image with the matching tag (`1.0.2-10-amd64`).
100+
The same command can be used for running on an amd64 system, since Docker discovers it is running on a amd64 host and pulls the image with the matching tag (`1.0.2-10-amd64`).
122101

123-
This gives the advantage that you don't need to know/specify which architecture you are running on and makes docker run commands and docker compose files more flexible and exchangeable across systems.
102+
This has the advantage that you don't need to know/specify which architecture you are running on and makes docker run commands and docker compose files more flexible and exchangeable across systems.
124103

125104
**Note**: Currently there is a bug in Docker's architecture detection that fails for Arm6 CPU - eg Raspberry Pi Zero or 1. For these devices you currently need to specify the full build label, for example:
126105
```
127-
docker run -it -p 1880:1880 --name mynodered nodered/node-red:1.0.2-10-minimal-arm32v6
106+
docker run -it -p 1880:1880 --name mynodered nodered/node-red:1.0.2-10-arm32v6
128107
```
129108

130-
131-
### Raspberry PI - native GPIO support
132-
| v1.0 - BREAKING: Native GPIO support for Raspberry PI has been dropped |
133-
| --- |
134-
The replacement for native GPIO is [node-red-node-pi-gpiod](https://github.com/node-red/node-red-nodes/tree/master/hardware/pigpiod).
135-
136-
Disadvantages of the native GPIO support are:
137-
- Your Docker container needs to be deployed on the same Docker node/host on which you want to control the gpio.
138-
- Gain access to `/dev/mem` of your Docker node/host
139-
- privileged=true is not supported for `docker stack` command
140-
141-
`node-red-node-pi-gpiod` fixes all these disadvantages. With `node-red-node-pi-gpiod` it is possible to interact with gpio of multiple Raspberry Pi's from a single Node-RED container, and for multiple containers to access different gpio on the same Pi.
142-
143-
#### Quick Migration steps to `node-red-node-pi-gpiod`
144-
1. Install `node-red-node-pi-gpiod` through the Node-RED palette
145-
2. Install and run `PiGPIOd daemon` on the host Pi.
146-
3. Replace all native gpio nodes with `pi gpiod` nodes.
147-
4. Configure `pi gpiod` nodes to connect to `PiGPIOd daemon`. Often the host machine will have an IP 172.17.0.1 port 8888 - but not always. You can use `docker exec -it mynodered ip route show default | awk '/default/ {print $3}'` to check.
148-
149-
For detailed install instruction please refer to the `node-red-node-pi-gpiod` [README](https://github.com/node-red/node-red-nodes/tree/master/hardware/pigpiod#node-red-node-pi-gpiod)
150-
151-
**Note**: There is a contributed [gpiod project](https://github.com/corbosman/node-red-gpiod) that runs the gpiod in its own container rather than on the host if required.
152-
153109
### Managing User Data
154110

155111
Once you have Node-RED running with Docker, we need to
@@ -183,34 +139,35 @@ to store persistent or shared data outside the container.
183139

184140
To create a new named data volume to persist our user data and run a new
185141
container using this volume.
186-
187-
$ docker volume create --name node_red_user_data
188-
$ docker volume ls
189-
DRIVER VOLUME NAME
190-
local node_red_user_data
191-
$ docker run -it -p 1880:1880 -v node_red_user_data:/data --name mynodered nodered/node-red
142+
```
143+
$ docker volume create --name node_red_user_data
144+
$ docker volume ls
145+
DRIVER VOLUME NAME
146+
local node_red_user_data
147+
$ docker run -it -p 1880:1880 -v node_red_user_data:/data --name mynodered nodered/node-red
148+
```
192149

193150
Using Node-RED to create and deploy some sample flows, we can now destroy the
194151
container and start a new instance without losing our user data.
195-
196-
$ docker rm mynodered
197-
$ docker run -it -p 1880:1880 -v node_red_user_data:/data --name mynodered nodered/node-red
152+
```
153+
$ docker rm mynodered
154+
$ docker run -it -p 1880:1880 -v node_red_user_data:/data --name mynodered nodered/node-red
155+
```
198156

199157
### Updating
200158

201159
As the /data is now preserved outside of the container, updating the base container image
202160
is now as simple as
203-
204-
$ docker pull nodered/node-red
205-
$ docker stop mynodered
206-
$ docker start mynodered
207-
161+
```
162+
$ docker pull nodered/node-red
163+
$ docker stop mynodered
164+
$ docker start mynodered
165+
```
208166

209167
### Docker Stack / Docker Compose
210168

211169
Below an example of a Docker Compose file which can be run by `docker stack` or `docker-compose`.
212170
Please refer to the official Docker pages for more info about [Docker stack](https://docs.docker.com/engine/reference/commandline/stack/) and [Docker compose](https://docs.docker.com/compose/).
213-
214171
```
215172
################################################################################
216173
# Node-RED Stack or Compose
@@ -240,17 +197,16 @@ networks:
240197
```
241198

242199
The above compose file:
243-
- creates a node-red service
244-
- pulls the latest node-red image
245-
- sets the timezone to Europe/Amsterdam
246-
- Maps the container port 1880 to the the host port 1880
247-
- creates a node-red-net network and attaches the container to this network
248-
- persists the `/data` dir inside the container to the `/mnt/docker-cluster/node-red/data` dir outside the container
200+
- creates a node-red service
201+
- pulls the latest node-red image
202+
- sets the timezone to Europe/Amsterdam
203+
- Maps the container port 1880 to the the host port 1880
204+
- creates a node-red-net network and attaches the container to this network
205+
- persists the `/data` dir inside the container to the `node-red-data` volume in Docker
249206

250-
#### Startup
207+
### Startup
251208

252-
Node-RED is started using NPM start from this `/usr/src/node-red`, with the `--userDir`
253-
parameter pointing to the `/data` directory on the container.
209+
Environment variables can be passed in to the container configure the runtime of Node-RED.
254210

255211
The flows configuration file is set using an environment parameter (**FLOWS**),
256212
which defaults to *'flows.json'*. This can be changed at runtime using the
@@ -262,52 +218,53 @@ docker run -it -p 1880:1880 -e FLOWS=my_flows.json nodered/node-red
262218
**Note**: If you set `-e FLOWS=""` then the flow file can be set via the *flowFile*
263219
property in the `settings.js` file.
264220

221+
Other useful environment variables include
222+
223+
- `-e NODE_RED_ENABLE_SAFE_MODE=false` # setting to true starts Node-RED in safe (not running) mode
224+
- `-e NODE_RED_ENABLE_PROJECTS=false` # setting to true starts Node-RED with the projects feature enabled
225+
265226
Node.js runtime arguments can be passed to the container using an environment
266227
parameter (**NODE_OPTIONS**). For example, to fix the heap size used by
267228
the Node.js garbage collector you would use the following command.
268229
```
269230
docker run -it -p 1880:1880 -e NODE_OPTIONS="--max_old_space_size=128" nodered/node-red
270231
```
271232

272-
Other useful environment variables include
233+
### Running headless
234+
235+
The barest minimum we need to just run Node-RED is
236+
237+
$ docker run -d -p 1880 --name mynodered nodered/node-red
238+
239+
This will create a local running instance of a machine - that will have some
240+
docker id number and be running on a random port... to find out run
241+
242+
$ docker ps
243+
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
244+
dd78e5bab6c4 nodered/node-red "npm start -- --user…" 7 seconds ago Up 5 seconds 0.0.0.0:32768->1880/tcp charming_chatterjee
245+
$
246+
247+
You can now point a browser to the host machine on the tcp port reported back, so in the example
248+
above browse to `http://{host ip}:32768`
273249

274-
- -e NODE_RED_ENABLE_SAFE_MODE=false # setting to true starts Node-RED in safe (not running) mode
275-
- -e NODE_RED_ENABLE_PROJECTS=false # setting to true starts Node-RED with the projects feature enabled
250+
### Container Shell
276251

277-
#### Container Shell
252+
Once it is running headless you can use the following command to get access back into the container.
278253
```
279254
$ docker exec -it mynodered /bin/bash
280255
```
281256

282257
Will give a command line inside the container - where you can then run the npm install
283258
command you wish - e.g.
284259
```
285-
$ cd /data
286-
$ npm install node-red-node-smooth
287-
$ exit
260+
bash-4.4$ npm install node-red-dashboard
261+
bash-4.4$ exit
288262
$ docker stop mynodered
289263
$ docker start mynodered
290264
```
291265

292266
Refreshing the browser page should now reveal the newly added node in the palette.
293267

294-
### Running headless
295-
296-
The barest minimum we need to just run Node-RED is
297-
298-
$ docker run -d -p 1880:1880 nodered/node-red
299-
300-
This will create a local running instance of a machine - that will have some
301-
docker id number and be running on a random port... to find out run
302-
303-
$ docker ps
304-
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
305-
4bbeb39dc8dc nodered/node-red:latest "npm start" 4 seconds ago Up 4 seconds 0.0.0.0:49154->1880/tcp furious_yalow
306-
$
307-
308-
You can now point a browser to the host machine on the tcp port reported back, so in the example
309-
above browse to `http://{host ip}:49154`
310-
311268
### Linking Containers
312269

313270
You can link containers "internally" within the docker runtime by using the --link option.
@@ -333,6 +290,28 @@ Then a simple flow like below should work - using the alias *broker* we just set
333290
This way the internal broker is not exposed outside of the docker host - of course
334291
you may add `-p 1883:1883` etc to the broker run command if you want to see it...
335292

293+
### Raspberry PI - native GPIO support
294+
| v1.0 - BREAKING: Native GPIO support for Raspberry PI has been dropped |
295+
| --- |
296+
The replacement for native GPIO is [node-red-node-pi-gpiod](https://github.com/node-red/node-red-nodes/tree/master/hardware/pigpiod).
297+
298+
Disadvantages of the native GPIO support are:
299+
- Your Docker container needs to be deployed on the same Docker node/host on which you want to control the gpio.
300+
- Gain access to `/dev/mem` of your Docker node/host
301+
- privileged=true is not supported for `docker stack` command
302+
303+
`node-red-node-pi-gpiod` fixes all these disadvantages. With `node-red-node-pi-gpiod` it is possible to interact with gpio of multiple Raspberry Pi's from a single Node-RED container, and for multiple containers to access different gpio on the same Pi.
304+
305+
#### Quick Migration steps to `node-red-node-pi-gpiod`
306+
307+
1. Install `node-red-node-pi-gpiod` through the Node-RED palette.
308+
2. Install and run `PiGPIOd daemon` on the host Pi. For detailed install instruction please refer to the `node-red-node-pi-gpiod` [README](https://github.com/node-red/node-red-nodes/tree/master/hardware/pigpiod#node-red-node-pi-gpiod).
309+
3. Replace all native gpio nodes with `pi gpiod` nodes.
310+
4. Configure `pi gpiod` nodes to connect to `PiGPIOd daemon`. Often the host machine will have an IP 172.17.0.1 port 8888 - but not always. You can use `docker exec -it mynodered ip route show default | awk '/default/ {print $3}'` to check.
311+
312+
**Note**: There is a contributed [gpiod project](https://github.com/corbosman/node-red-gpiod) that runs the gpiod in its own container rather than on the host if required.
313+
314+
---
336315

337316
### Common Issues and Hints
338317

@@ -368,7 +347,6 @@ https://github.com/node-red/node-red/issues/15
368347
#### Setting Timezone
369348

370349
If you want to modify the default timezone, use the TZ environment variable with the [relevant timezone](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).
371-
372350
```
373351
docker run -it -p 1880:1880 --name mynodered -e TZ=Europe/London nodered/node-red
374352
```

0 commit comments

Comments
 (0)