Skip to content

Commit

Permalink
2023-10-14 documentation - master branch
Browse files Browse the repository at this point in the history
Replaces all example commands in the following format:

```
$ docker-compose rm --force --stop -v «container»
```

with example commands in the this format:

```
$ docker-compose down «container»
```

The Getting Started document includes a note explaining that any error
returned by `docker-compose down` to the effect that it does not support
`«container»` arguments implies that the user's version of
`docker-compose` is obsolete and should be updated.

Where any container's documentation has had `rm` replaced with `down`,
that is followed by a note pointing to the Getting Started explanation.

Also, I took the opportunity to fix the following error returned by
`mkdocs`:

```
INFO    -  Doc file 'index.md' contains an unrecognized relative link 'Developers/', it was left as is. Did you mean 'Developers/index.md'?
```

Signed-off-by: Phill Kelley <[email protected]>
  • Loading branch information
Paraphraser committed Oct 14, 2023
1 parent 2cc7488 commit ed168c3
Show file tree
Hide file tree
Showing 17 changed files with 79 additions and 30 deletions.
13 changes: 11 additions & 2 deletions docs/Basic_setup/index.md
100644 → 100755
Original file line number Diff line number Diff line change
Expand Up @@ -409,13 +409,22 @@ $ cd ~/IOTstack
$ docker-compose start «container»
```

There is no equivalent of `down` for a single container. It needs:
You can also `down` a container:

``` console
$ cd ~/IOTstack
$ docker-compose rm --force --stop -v «container»
$ docker-compose down «container»
```

<a name="downContainer"></a>Note:

* If the `down` command returns an error suggesting that you can't use it to down a container, it actually means that you have an obsolete version of `docker-compose`. You should upgrade your system. The workaround is to you the old syntax:

``` console
$ cd ~/IOTstack
$ docker-compose rm --force --stop -v «container»
```

To reactivate a container which has been stopped and removed:

``` console
Expand Down
6 changes: 4 additions & 2 deletions docs/Containers/Blynk_server.md
100644 → 100755
Original file line number Diff line number Diff line change
Expand Up @@ -164,11 +164,11 @@ Erasing Blynk Server's persistent storage area triggers self-healing and restore

```console
$ cd ~/IOTstack
$ docker-compose rm --force --stop -v blynk_server
$ docker-compose down blynk_server
$ sudo rm -rf ./volumes/blynk_server
$ docker-compose up -d blynk_server
```
Note:
Notes:

* You can also remove individual configuration files and then trigger self-healing. For example, if you decide to edit `server.properties` and make a mess, you can restore the original default version like this:

Expand All @@ -177,6 +177,8 @@ Note:
$ rm volumes/blynk_server/config/server.properties
$ docker-compose restart blynk_server
```

* See also [if downing a container doesn't work](../Basic_setup/index.md/#downContainer)

## Upgrading Blynk Server { #upgradingBlynkServer }

Expand Down
4 changes: 3 additions & 1 deletion docs/Containers/Grafana.md
100644 → 100755
Original file line number Diff line number Diff line change
Expand Up @@ -122,9 +122,11 @@ Begin by stopping Grafana:

``` console
$ cd ~/IOTstack
$ docker-compose rm --force --stop -v grafana
$ docker-compose down grafana
```

> see also [if downing a container doesn't work](../Basic_setup/index.md/#downContainer)

You have two options:

1. Destroy your settings and dashboards but retain any plugins you may have installed:
Expand Down
8 changes: 6 additions & 2 deletions docs/Containers/InfluxDB2.md
100644 → 100755
Original file line number Diff line number Diff line change
Expand Up @@ -202,11 +202,13 @@ To migrate your InfluxDB&nbsp;1.8 data:

```bash
$ sudo rm -rf ./volumes/influxdb.migrate
$ docker-compose rm --force --stop -v influxdb
$ docker-compose down influxdb
$ sudo cp -a ./volumes/influxdb ./volumes/influxdb.migrate
$ docker-compose up -d influxdb
$ sudo chown -R 1000:1000 ./volumes/influxdb.migrate/data
```

> see also [if downing a container doesn't work](../Basic_setup/index.md/#downContainer)

In words:

Expand Down Expand Up @@ -349,8 +351,10 @@ If you need to start over from a clean slate:
2. Terminate the InfluxDB&nbsp;2 container:

```bash
$ docker-compose rm --force --stop -v influxdb2
$ docker-compose down influxdb2
```

> see also [if downing a container doesn't work](../Basic_setup/index.md/#downContainer)

3. Remove the persistent store:

Expand Down
4 changes: 3 additions & 1 deletion docs/Containers/MariaDB.md
100644 → 100755
Original file line number Diff line number Diff line change
Expand Up @@ -38,9 +38,11 @@ You only get the opportunity to change the `MQSL_` prefixed environment variable

``` console
$ cd ~/IOTstack
$ docker-compose rm --force --stop -v mariadb
$ docker-compose down mariadb
$ sudo rm -rf ./volumes/mariadb
```
> see also [if downing a container doesn't work](../Basic_setup/index.md/#downContainer)

* Edit `docker-compose.yml` and change the variables.
* Bring up the container:
Expand Down
4 changes: 3 additions & 1 deletion docs/Containers/MotionEye.md
Original file line number Diff line number Diff line change
Expand Up @@ -109,8 +109,10 @@ Although it depends on your exact settings, MotionEye's video storage can repres
2. Terminate the motioneye container:

``` bash
$ docker-compose rm --force --stop -v motioneye
$ docker-compose down motioneye
```

> see also [if downing a container doesn't work](../Basic_setup/index.md/#downContainer)

3. Move the video storage folder:

Expand Down
7 changes: 5 additions & 2 deletions docs/Containers/NextCloud.md
100644 → 100755
Original file line number Diff line number Diff line change
Expand Up @@ -75,6 +75,8 @@ The passwords need to be set before you bring up the Nextcloud service for the f
```console
$ docker-compose down
```

> see also [if downing a container doesn't work](../Basic_setup/index.md/#downContainer)

3. Erase the persistent storage area for Nextcloud (double-check the command *before* you hit return):

Expand Down Expand Up @@ -309,7 +311,7 @@ If you want to take a backup, something like the following will get the job done
$ cd ~/IOTstack
$ BACKUP_TAR_GZ=$PWD/backups/$(date +"%Y-%m-%d_%H%M").$HOSTNAME.nextcloud-backup.tar.gz
$ touch "$BACKUP_TAR_GZ"
$ docker-compose rm --force --stop -v nextcloud nextcloud_db
$ docker-compose down nextcloud nextcloud_db
$ sudo tar -czf "$BACKUP_TAR_GZ" -C "./volumes/nextcloud" .
$ docker-compose up -d nextcloud
```
Expand All @@ -318,13 +320,14 @@ Notes:

* A *baseline* backup takes over 400MB and about 2 minutes. Once you start adding your own data, it will take even more time and storage.
* The `up` of the NextCloud container implies the `up` of the Nextcloud_DB container.
* See also [if downing a container doesn't work](../Basic_setup/index.md/#downContainer)

To restore, you first need to identify the name of the backup file by looking in the `backups` directory. Then:

```console
$ cd ~/IOTstack
$ RESTORE_TAR_GZ=$PWD/backups/2021-06-12_1321.sec-dev.nextcloud-backup.tar.gz
$ docker-compose rm --force --stop -v nextcloud nextcloud_db
$ docker-compose down nextcloud nextcloud_db
$ sudo rm -rf ./volumes/nextcloud/*
$ sudo tar -x --same-owner -z -f "$RESTORE_TAR_GZ" -C "./volumes/nextcloud"
$ docker-compose up -d nextcloud
Expand Down
4 changes: 3 additions & 1 deletion docs/Containers/Node-RED.md
100644 → 100755
Original file line number Diff line number Diff line change
Expand Up @@ -975,9 +975,11 @@ To stop the running container:

``` console
$ cd ~/IOTstack
$ docker-compose rm --force --stop -v nodered
$ docker-compose down nodered
```

> see also [if downing a container doesn't work](../Basic_setup/index.md/#downContainer)

Alternatively, you can stop the entire stack:

``` console
Expand Down
4 changes: 3 additions & 1 deletion docs/Containers/Pi-hole.md
Original file line number Diff line number Diff line change
Expand Up @@ -496,10 +496,12 @@ The recommended approach is:

``` console
$ cd ~/IOTstack
$ docker-compose rm --force --stop -v pihole
$ docker-compose down pihole
$ sudo rm -rf ./volumes/pihole
$ docker-compose up -d pihole
```

> see also [if downing a container doesn't work](../Basic_setup/index.md/#downContainer)

5. Login to Pi-hole's web GUI and navigate to Settings » Teleporter.
6. Use the checkboxes to select the settings you wish to restore, and click the <kbd>Browse</kbd> and <kbd>Restore</kbd> buttons.
Expand Down
4 changes: 3 additions & 1 deletion docs/Containers/PostgreSQL.md
100644 → 100755
Original file line number Diff line number Diff line change
Expand Up @@ -85,7 +85,9 @@ If you need to start over, proceed like this:

``` console
$ cd ~/IOTstack
$ docker-compose rm --force --stop -v postgres
$ docker-compose down postgres
$ sudo rm -rf ./volumes/postgres
$ docker-compose up -d postgres
```

> see also [if downing a container doesn't work](../Basic_setup/index.md/#downContainer)
4 changes: 3 additions & 1 deletion docs/Containers/Prometheus.md
100644 → 100755
Original file line number Diff line number Diff line change
Expand Up @@ -24,8 +24,10 @@

```
$ cd ~/IOTstack
$ docker-compose rm --force --stop -v prometheus prometheus-cadvisor prometheus-nodeexporter
$ docker-compose down prometheus prometheus-cadvisor prometheus-nodeexporter
```

> see also [if downing a container doesn't work](../Basic_setup/index.md/#downContainer)

2. Move the existing active configuration out of the way:

Expand Down
12 changes: 8 additions & 4 deletions docs/Containers/Python.md
100644 → 100755
Original file line number Diff line number Diff line change
Expand Up @@ -154,8 +154,10 @@ To stop the container from running, either:

``` console
$ cd ~/IOTstack
$ docker-compose rm --force --stop -v python
$ docker-compose down python
```

> see also [if downing a container doesn't work](../Basic_setup/index.md/#downContainer)

## starting the Python service { #startPython }

Expand Down Expand Up @@ -255,11 +257,13 @@ If you make a mess of things and need to start from a clean slate, erase the per

``` console
$ cd ~/IOTstack
$ docker-compose rm --force --stop -v python
$ docker-compose down python
$ sudo rm -rf ./volumes/python
$ docker-compose up -d python
```

> see also [if downing a container doesn't work](../Basic_setup/index.md/#downContainer)
The container will re-initialise the persistent storage area from its defaults.

### adding packages { #addingPackages }
Expand Down Expand Up @@ -377,7 +381,7 @@ Suppose the Python script you have been developing reaches a major milestone and

``` console
$ cd ~/IOTstack
$ docker-compose rm --force --stop -v python
$ docker-compose down python
$ sudo rm -rf ./volumes/python
```

Expand Down Expand Up @@ -419,7 +423,7 @@ Proceed like this:

``` console
$ cd ~/IOTstack
$ docker-compose rm --force --stop -v python
$ docker-compose down python
```

2. Remove the existing local image:
Expand Down
4 changes: 3 additions & 1 deletion docs/Containers/Scrypted.md
100644 → 100755
Original file line number Diff line number Diff line change
Expand Up @@ -72,11 +72,13 @@ If you need to start over from scratch:

``` console
$ cd ~/IOTstack
$ docker-compose rm --force --stop -v scrypted
$ docker-compose down scrypted
$ sudo rm -rf ./volumes/scrypted
$ docker-compose up -d scrypted
```

> see also [if downing a container doesn't work](../Basic_setup/index.md/#downContainer)
## About the service definition

The Scrypted container runs in host mode, which means it binds directly to the Raspberry Pi's ports. The service definition includes:
Expand Down
10 changes: 6 additions & 4 deletions docs/Containers/Telegraf.md
100644 → 100755
Original file line number Diff line number Diff line change
Expand Up @@ -252,12 +252,12 @@ Erasing Telegraf's persistent storage area triggers self-healing and restores kn

``` console
$ cd ~/IOTstack
$ docker-compose rm --force --stop -v telegraf
$ docker-compose down telegraf
$ sudo rm -rf ./volumes/telegraf
$ docker-compose up -d telegraf
```

Note:
Notes:

* You can also remove individual files within the persistent storage area and then trigger self-healing. For example, if you decide to edit `telegraf-reference.conf` and make a mess, you can restore the original version like this:

Expand All @@ -267,13 +267,15 @@ Note:
$ docker-compose restart telegraf
```

* See also [if downing a container doesn't work](../Basic_setup/index.md/#downContainer)

### Resetting the InfluxDB database { #resetDB }

To reset the InfluxDB database that Telegraf writes into, proceed like this:

``` console
$ cd ~/IOTstack
$ docker-compose rm --force --stop -v telegraf
$ docker-compose down telegraf
$ docker exec -it influxdb influx -precision=rfc3339
> drop database telegraf
> exit
Expand All @@ -283,7 +285,7 @@ $ docker-compose up -d telegraf
In words:

* Be in the right directory.
* Stop the Telegraf container (while leaving the InfluxDB container running).
* Stop the Telegraf container (while leaving the InfluxDB container running). See also [if downing a container doesn't work](../Basic_setup/index.md/#downContainer).
* Launch the Influx CLI inside the InfluxDB container.
* Delete the `telegraf` database, and then exit the CLI.
* Start the Telegraf container. This re-creates the database automatically.
Expand Down
8 changes: 6 additions & 2 deletions docs/Containers/WireGuard.md
100644 → 100755
Original file line number Diff line number Diff line change
Expand Up @@ -616,10 +616,12 @@ IOTstack users implementing WireGuard for the first time will get the correct st

``` console
$ cd ~/IOTstack
$ docker-compose rm --force --stop -v wireguard
$ docker-compose down wireguard
$ ./scripts/2022-10-01-wireguard-restructure.sh
```

> see also [if downing a container doesn't work](../Basic_setup/index.md/#downContainer)

In words:

* Be in the correct directory
Expand Down Expand Up @@ -665,8 +667,10 @@ The procedure is:

``` console
$ cd ~/IOTstack
$ docker-compose rm --force --stop -v wireguard
$ docker-compose down wireguard
```

> see also [if downing a container doesn't work](../Basic_setup/index.md/#downContainer)

2. Erase the persistent storage area (essential):

Expand Down
11 changes: 8 additions & 3 deletions docs/Containers/ZeroTier.md
100644 → 100755
Original file line number Diff line number Diff line change
Expand Up @@ -209,8 +209,10 @@ The ZeroTier-router container is just the ZeroTier-client container with some `i

``` console
$ cd ~/IOTstack
$ docker-compose rm --force --stop -v zerotier-client
$ docker-compose down zerotier-client
```

> See also [if downing a container doesn't work](../Basic_setup/index.md/#downContainer)

2. Remove the existing service definition, either by:

Expand Down Expand Up @@ -969,11 +971,14 @@ You can erase ZeroTier's persistent storage area like this:

``` console
$ cd ~/IOTstack
$ docker-compose rm --force --stop -v {zerotier-client | zerotier-router}
$ docker-compose down {zerotier-client | zerotier-router}
$ sudo rm -rf ./volumes/zerotier-one
```

> Tip: always double-check `sudo` commands **before** hitting <kbd>Enter</kbd>.
Tips:

1. always double-check `sudo` commands **before** hitting <kbd>Enter</kbd>.
2. see also [if downing a container doesn't work](../Basic_setup/index.md/#downContainer)

Erasing persistent storage destroys the client's authorisation (cryptographic credentials). If you start the container again, it will construct a new identity and you will need to re-authorise the client in ZeroTier Central. You should also delete the obsolete client authorisation.

Expand Down
2 changes: 1 addition & 1 deletion docs/index.md
100644 → 100755
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ Welcome to IOTstack:

* You're always welcome to ask questions on the [IOTStack Discord](https://discord.gg/ZpKHnks).

* Fixes and improvements welcome, see [Contributing](Developers/)
* Fixes and improvements welcome, see [Contributing](./Developers/index.md)

!!! cite inline end "Full site page listing"

Expand Down

0 comments on commit ed168c3

Please sign in to comment.