Skip to content

Commit 229dab1

Browse files
SlykeSlyke
authored
Merge pull request #579 from ukkopahis/doc-improvements
Doc improvements
2 parents ee4d3fe + c0c5301 commit 229dab1

File tree

7 files changed

+109
-68
lines changed

7 files changed

+109
-68
lines changed

‎README.md

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,19 @@
22

33
IOTstack is a builder for docker-compose to easily make and maintain IoT stacks on the Raspberry Pi.
44

5+
## introduction to IOTstack - videos
6+
7+
These are from 2019 and 2020. Though IOTstack has changed quite a bit, they are
8+
still a great overview
9+
10+
Andreas Spiess Video #295: Raspberry Pi Server based on Docker, with VPN, Dropbox backup, Influx, Grafana, etc: IOTstack
11+
12+
[![#295 Raspberry Pi Server based on Docker, with VPN, Dropbox backup, Influx, Grafana, etc: IOTstack](http://img.youtube.com/vi/a6mjt8tWUws/0.jpg)](https://www.youtube.com/watch?v=a6mjt8tWUws)
13+
14+
Andreas Spiess Video #352: Raspberry Pi4 Home Automation Server (incl. Docker, OpenHAB, HASSIO, NextCloud)
15+
16+
[![#352 Raspberry Pi4 Home Automation Server (incl. Docker, OpenHAB, HASSIO, NextCloud)](http://img.youtube.com/vi/KJRMjUzlHI8/0.jpg)](https://www.youtube.com/watch?v=KJRMjUzlHI8)
17+
518
### getting started
619

720
See [Getting Started](https://sensorsiot.github.io/IOTstack/Getting-Started) in the [IOTstack Wiki](https://sensorsiot.github.io/IOTstack/). It includes:

‎docs/Basic_setup/Troubleshooting.md

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
2+
## Resources
3+
4+
* Search github [issues](https://github.com/SensorsIot/IOTstack/issues?q=).
5+
Note: Also closed issues or pull-requests may have valuable hints.
6+
7+
* Ask questions on [IOTStack Discord](https://discord.gg/ZpKHnks). Or report
8+
how you were able to fix a problem.
9+
10+
* There are over 40 gists about IOTstack. These address a diverse range of
11+
topics from small convenience scripts to complete guides. These are
12+
individual contributions that aren't reviewed.
13+
14+
You can add your own keywords into the search:
15+
[https://gist.github.com/search?q=iotstack](https://gist.github.com/search?q=iotstack)
16+
17+
## FAQ
18+
19+
!!! danger "Breaking update"
20+
A change done 2022-01-18 will require [manual steps](
21+
../Updates/migration-network-change.md)
22+
or you may get an error like:
23+
`ERROR: Service "influxdb" uses an undefined network "iotstack_nw"`
24+
25+
26+
## Getting a clean slate
27+
28+
If you create a mess and can't see how to recover, try proceeding like this:
29+
30+
``` console
31+
$ cd ~/IOTstack
32+
$ docker-compose down
33+
$ cd
34+
$ mv IOTstack IOTstack.old
35+
$ git clone https://github.com/SensorsIot/IOTstack.git IOTstack
36+
```
37+
38+
In words:
39+
40+
1. Be in the right directory.
41+
2. Take the stack down.
42+
3. The `cd` command without any arguments changes your working directory to
43+
your home directory (variously known as `~` or `$HOME` or `/home/pi`).
44+
4. Move your existing IOTstack directory out of the way. If you get a
45+
permissions problem:
46+
47+
* Re-try the command with `sudo`; and
48+
* Read [a word about the `sudo` command](What-is-sudo.md). Needing `sudo`
49+
in this situation is an example of over-using `sudo`.
50+
51+
5. Check out a clean copy of IOTstack.
52+
53+
Now, you have a clean slate and can start afresh by running the menu:
54+
55+
``` console
56+
$ cd ~/IOTstack
57+
$ ./menu.sh
58+
```
59+
60+
The `IOTstack.old` directory remains available as a reference for as long as
61+
you need it. Once you have no further use for it, you can clean it up via:
62+
63+
``` console
64+
$ cd
65+
$ sudo rm -rf ./IOTstack.old # (1)
66+
```
67+
68+
1. The `sudo` command is needed in this situation because some files and
69+
folders (eg the "volumes" directory and most of its contents) are owned by
70+
root.

‎docs/Basic_setup/index.md

Lines changed: 1 addition & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,6 @@
11
# Getting Started
22

3-
## introduction to IOTstack - videos
4-
5-
Andreas Spiess Video #295: Raspberry Pi Server based on Docker, with VPN, Dropbox backup, Influx, Grafana, etc: IOTstack
6-
7-
[![#295 Raspberry Pi Server based on Docker, with VPN, Dropbox backup, Influx, Grafana, etc: IOTstack](http://img.youtube.com/vi/a6mjt8tWUws/0.jpg)](https://www.youtube.com/watch?v=a6mjt8tWUws)
8-
9-
Andreas Spiess Video #352: Raspberry Pi4 Home Automation Server (incl. Docker, OpenHAB, HASSIO, NextCloud)
10-
11-
[![#352 Raspberry Pi4 Home Automation Server (incl. Docker, OpenHAB, HASSIO, NextCloud)](http://img.youtube.com/vi/KJRMjUzlHI8/0.jpg)](https://www.youtube.com/watch?v=KJRMjUzlHI8)
12-
13-
## Assumptions
3+
## Requirements
144

155
IOTstack makes the following assumptions:
166

@@ -748,49 +738,3 @@ To pin an image to a specific version:
748738
$ docker-compose up -d --build mosquitto
749739
```
750740

751-
## the nuclear option - use with caution
752-
753-
If you create a mess and can't see how to recover, try proceeding like this:
754-
755-
``` console
756-
$ cd ~/IOTstack
757-
$ docker-compose down
758-
$ cd
759-
$ mv IOTstack IOTstack.old
760-
$ git clone https://github.com/SensorsIot/IOTstack.git IOTstack
761-
```
762-
763-
In words:
764-
765-
1. Be in the right directory.
766-
2. Take the stack down.
767-
3. The `cd` command without any arguments changes your working directory to your home directory (variously known as `~` or `$HOME` or `/home/pi`).
768-
4. Move your existing IOTstack directory out of the way. If you get a permissions problem:
769-
770-
* Re-try the command with `sudo`; and
771-
* Read [a word about the `sudo` command](#a-word-about-the-sudo-command). Needing `sudo` in this situation is an example of over-using `sudo`.
772-
773-
5. Check out a clean copy of IOTstack.
774-
775-
Now, you have a clean slate. You can either start afresh by running the menu:
776-
777-
``` console
778-
$ cd ~/IOTstack
779-
$ ./menu.sh
780-
```
781-
782-
Alternatively, you can mix and match by making selective copies from the old directory. For example:
783-
784-
``` console
785-
$ cd
786-
$ cp IOTstack.old/docker-compose.yml IOTstack/
787-
```
788-
789-
The `IOTstack.old` directory remains available as a reference for as long as you need it. Once you have no further use for it, you can clean it up via:
790-
791-
``` console
792-
$ cd
793-
$ sudo rm -rf ./IOTstack.old
794-
```
795-
796-
The `sudo` command is needed in this situation because some files and folders (eg the "volumes" directory and most of its contents) are owned by root.

‎docs/Containers/Home-Assistant.md

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -177,8 +177,8 @@ your RPi hostname is raspberrypi)
177177
sudo chmod u+x volumes/swag/config/custom-cont-init.d/add-host.docker.internal.sh
178178
```
179179

180-
(This needs to be copy-pasted/entered as-is, ignore any "> "-prefixes printed
181-
by bash)
180+
(This needs to be copy-pasted/entered as-is, ignore any "> "-prefixes printed
181+
by bash)
182182

183183
8. (optional) Add reverse proxy password protection if you don't want to rely
184184
on the HA login for security, doesn't affect API-access:
@@ -195,14 +195,14 @@ your RPi hostname is raspberrypi)
195195
file is at `volumes/home_assistant/configuration.yaml` For a default install
196196
the resulting http-section should be:
197197

198-
```yaml
199-
http:
200-
use_x_forwarded_for: true
201-
trusted_proxies:
202-
- 192.168.0.0/16
203-
- 172.16.0.0/12
204-
- 10.77.0.0/16
205-
```
198+
```yaml
199+
http:
200+
use_x_forwarded_for: true
201+
trusted_proxies:
202+
- 192.168.0.0/16
203+
- 172.16.0.0/12
204+
- 10.77.0.0/16
205+
```
206206
207207
10. Refresh the stack: `cd ~/IOTstack && docker-compose stop && docker-compose
208208
up -d` (again may take 1-3 minutes for swag to start if it recreates

‎docs/Developers/index.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -98,4 +98,4 @@ Links:
9898
* [Password configuration for Services](BuildStack-RandomPassword.md)
9999
* [Build Stack Menu System](Menu-System.md)
100100
* [Coding a new service](BuildStack-Services.md)
101-
* [IOTstack issues](htps://github.com/SensorsIot/IOTstack/issues)
101+
* [IOTstack issues](https://github.com/SensorsIot/IOTstack/issues)

‎docs/index.md

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,3 +28,16 @@ Welcome to IOTstack:
2828
!!! cite inline end "Full site page listing"
2929

3030
{nav}
31+
32+
## introduction to IOTstack - videos
33+
34+
These are from 2019 and 2020. Though IOTstack has changed a bit, they are still
35+
a great introduction.
36+
37+
Andreas Spiess Video #295: Raspberry Pi Server based on Docker, with VPN, Dropbox backup, Influx, Grafana, etc: IOTstack
38+
39+
[![#295 Raspberry Pi Server based on Docker, with VPN, Dropbox backup, Influx, Grafana, etc: IOTstack](http://img.youtube.com/vi/a6mjt8tWUws/0.jpg)](https://www.youtube.com/watch?v=a6mjt8tWUws)
40+
41+
Andreas Spiess Video #352: Raspberry Pi4 Home Automation Server (incl. Docker, OpenHAB, HASSIO, NextCloud)
42+
43+
[![#352 Raspberry Pi4 Home Automation Server (incl. Docker, OpenHAB, HASSIO, NextCloud)](http://img.youtube.com/vi/KJRMjUzlHI8/0.jpg)](https://www.youtube.com/watch?v=KJRMjUzlHI8)

‎mkdocs.yml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,7 @@ theme:
2323
icon: material/weather-night
2424
name: Switch to light mode
2525
features:
26+
- content.code.annotate
2627
- tabs
2728
- navigation.tabs
2829
- navigation.tabs.sticky

0 commit comments

Comments
 (0)