WIP Docs V2

.github/workflows/main.yml

@@ -9,10 +9,10 @@ jobs:
     name: Deploy docs
     runs-on: ubuntu-latest
     steps:
-      - name: Checkout master
-        uses: actions/checkout@v1
-
-      - name: Deploy docs
-        uses: mhausenblas/mkdocs-deploy-gh-pages@master
-        env:
-          PERSONAL_TOKEN: ${{ secrets.PERSONAL_TOKEN }}
+      - uses: actions/checkout@v2
+      - uses: actions/setup-python@v2
+        with:
+          python-version: 3.x
+      - run: pip install mkdocs-material
+      - run: pip install mkdocs-git-revision-date-localized-plugin
+      - run: mkdocs gh-deploy --force

docs/Backups/.pages

@@ -0,0 +1 @@
+title: Backups

docs/Containers/MariaDB.md → docs/Containers/Database/MariaDB.md

@@ -1,3 +1,4 @@
+# MariaDB
 ## Source
 * [Docker hub](https://hub.docker.com/r/linuxserver/mariadb/)
 * [Webpage](https://mariadb.org/)

docs/Containers/NextCloud.md

@@ -1,9 +1,7 @@
 # Next Cloud
-## DO NOT EXPOSE PORT 80 TO THE WEB
-
-It is a very bad idea to expose unencrypted traffic to the web. You will need to use a reverse-proxy to ensure your password is not stolen and your account hacked.
-
-I'm still working on getting a good encrypted reverse proxy working. However in the interim you can use a VPN tunnel like OpenVPN or Zerotier to securely connect to your private cloud
+!!! attention "DO NOT EXPOSE PORT 80 TO THE WEB"
+    It is a very bad idea to expose unencrypted traffic to the web. You will need to use a reverse-proxy to ensure your password is not stolen and your account hacked.
+    I'm still working on getting a good encrypted reverse proxy working. However in the interim you can use a VPN tunnel like OpenVPN or Zerotier to securely connect to your private cloud
 
 ## Backups
 
@@ -60,4 +58,4 @@ It would be a good idea to mount an external drive to store the data in rather t
 
 The external drive will have to be an ext4 formatted drive because smb, fat32 and NTFS can't handle linux file permissions. If the permissions aren't set to "www-data" then the container wont be able to write to the disk.
 
-Just a warning: If your database gets corrupted then your nextcloud is pretty much stuffed
+!!! warning "If your database gets corrupted then your nextcloud is pretty much stuffed"

docs/Docker/.pages

@@ -0,0 +1 @@
+title: Docker

docs/Docker/Understanding-Containers.md

@@ -0,0 +1,112 @@
+# Let’s begin by understanding, What is Docker?
+
+In simple terms, Docker is a software platform that simplifies the process of building, running, 
+managing and distributing applications. It does this by virtualizing the operating system of the 
+computer on which it is installed and running.
+
+# The Problem
+Let’s say you have three different Python-based applications that you plan to host on a single server 
+(which could either be a physical or a virtual machine).
+
+Each of these applications makes use of a different version of Python, as well as the associated 
+libraries and dependencies, differ from one application to another.
+
+Since we cannot have different versions of Python installed on the same machine, this prevents us from 
+hosting all three applications on the same computer.
+
+# The Solution
+Let’s look at how we could solve this problem without making use of Docker. In such a scenario, we 
+could solve this problem either by having three physical machines, or a single physical machine, which 
+is powerful enough to host and run three virtual machines on it.
+
+Both the options would allow us to install different versions of Python on each of these machines, 
+along with their associated dependencies.
+
+The machine on which Docker is installed and running is usually referred to as a Docker Host or Host in
+simple terms. So, whenever you plan to deploy an application on the host, it would create a logical 
+entity on it to host that application. In Docker terminology, we call this logical entity a Container or 
+Docker Container to be more precise.
+
+Whereas the kernel of the host’s operating system is shared across all the containers that are running 
+on it.
+
+This allows each container to be isolated from the other present on the same host. Thus it supports 
+multiple containers with different application requirements and dependencies to run on the same host, 
+as long as they have the same operating system requirements.
+
+# Docker Terminology
+
+Docker Images and Docker Containers are the two essential things that you will come across daily while 
+working with Docker.
+
+In simple terms, a Docker Image is a template that contains the application, and all the dependencies 
+required to run that application on Docker.
+
+On the other hand, as stated earlier, a Docker Container is a logical entity. In more precise terms, 
+it is a running instance of the Docker Image.
+
+# What is Docker-Compose?
+
+Docker Compose provides a way to orchestrate multiple containers that work together. Docker compose 
+is a simple yet powerful tool that is used to run multiple containers as a single service. 
+For example, suppose you have an application which requires Mqtt as a communication service between IOT devices
+and OpenHAB instance as a Smarthome application service. In this case by docker-compose, you can create one 
+single file (docker-compose.yml) which will create both the containers as a single service without starting 
+each separately. It wires up the networks (literally), mounts all volumes and exposes the ports.
+
+The IOTstack with the templates and menu is a generator for that docker-compose service descriptor.
+
+# How Docker Compose Works?
+
+use yaml files to configure application services (docker-compose.yaml)
+can start all the services with a single command ( docker-compose up )
+can stop all the service with a single command ( docker-compose down )
+
+# How are the containers connected
+The containers are automagically connected when we run the stack with docker-compose up. 
+The containers using same logical network (by default) where the instances can access each other with the instance 
+logical name. Means if there is an instance called *mosquitto* and an *openhab*, when openHAB instance need
+to access mqtt on that case the domain name of mosquitto will be resolved as the runnuning instance of mosquitto.
+
+# How the container are connected to host machine
+
+## Volumes
+
+The containers are enclosed processes which state are lost with the restart of container. To be able to 
+persist states volumes (images or directories) can be used to share data with the host. 
+Which means if you need to persist some database, configuration or any state you have to bind volumes where the 
+running service inside the container will write files to that binded volume.
+In order to understand what a Docker volume is, we first need to be clear about how the filesystem normally works 
+in Docker. Docker images are stored as series of read-only layers. When we start a container, Docker takes 
+the read-only image and adds a read-write layer on top. If the running container modifies an existing file, 
+the file is copied out of the underlying read-only layer and into the top-most read-write layer where the 
+changes are applied. The version in the read-write layer hides the underlying file, but does not 
+destroy it -- it still exists in the underlying layer. When a Docker container is deleted, 
+relaunching the image will start a fresh container without any of the changes made in the previously 
+running container -- those changes are lost, thats the reason that configs, databases are not persisted,
+
+Volumes are the preferred mechanism for persisting data generated by and used by Docker containers.
+While bind mounts are dependent on the directory structure of the host machine, volumes are completely 
+managed by Docker. In IOTstack project uses the volumes directory in general to bind these container volumes.
+
+## Ports
+When containers running a we would like to delegate some services to the outside world, for example
+OpenHAB web frontend have to be accessible for users. There are several ways to achive that. One is
+mounting the port to the most machine, this called port binding. On that case service will have a dedicated
+port which can be accessed, one drawback is one host port can be used one serice only. Another way is reverse proxy. 
+The term reverse proxy (or Load Balancer in some terminology) is normally applied to a service that sits in front 
+of one or more servers (in our case containers), accepting requests from clients for resources located on the 
+server(s). From the client point of view, the reverse proxy appears to be the web server and so is 
+totally transparent to the remote user. Which means several service can share same port the server
+will route the request by the URL (virtual domain or context path). For example, there is *grafana* and *openHAB*
+instances, where the *opeanhab.domain.tld* request will be routed to openHAB instance 8181 port while 
+*grafana.domain.tld* to grafana instance 3000 port. On that case the proxy have to be mapped for host port 80 and/or
+444 on host machine, the proxy server will access the containers via the docker virtual network.
+
+
+Source materials used:
+
+* https://takacsmark.com/docker-compose-tutorial-beginners-by-example-basics/
+* https://www.freecodecamp.org/news/docker-simplified-96639a35ff36/
+* https://www.cloudflare.com/learning/cdn/glossary/reverse-proxy/
+* https://blog.container-solutions.com/understanding-volumes-docker

docs/Native installs/.pages

@@ -0,0 +1 @@
+title: Native installs

docs/Containers/x2go.md → docs/Remote Access/x2go.md

@@ -1,3 +1,6 @@
+---
+title: x2go
+---
 # x2go
 x2go is an "alternative" to using VNC for a remote connection. It uses X11 forwarding over ssh to provide a desktop environment
 

docs/Updating-the-Project.md

@@ -1,5 +1,6 @@
 # Updating the project
-**If you ran the git checkout -- 'git ls-files -m' as suggested in the old wiki entry then please check your duck.sh because it removed your domain and token**
+!!! important
+    If you ran the git checkout -- 'git ls-files -m' as suggested in the old wiki entry then please check your duck.sh because it removed your domain and token
 
 
 Periodically updates are made to project which include new or modified container template, changes to backups or additional features. As these are released your local copy of this project will become out of date. This section deals with how to bring your project to the latest published state.

docs/index.md

@@ -9,6 +9,7 @@ https://sensorsiot.github.io/IOTstack/
 
 ## Video
 [![#295 Raspberry Pi Server based on Docker, with VPN, Dropbox backup, Influx, Grafana, etc.](http://img.youtube.com/vi/a6mjt8tWUws/0.jpg)](https://www.youtube.com/watch?v=a6mjt8tWUws "#295 Raspberry Pi Server based on Docker, with VPN, Dropbox backup, Influx, Grafana, etc.")
+
 **Andreas Spiess | #295 Raspberry Pi Server based on Docker, with VPN, Dropbox backup, Influx, Grafana, etc.**
 
 
@@ -62,4 +63,4 @@ Feel free to add your comments on features or images that you think should be ad
 
 ## Contributions
 
-If you use some of the tools in the project please consider donating or contributing on their projects. It doesn't have to be monetary, reporting bugs and PRs help improve the projects for everyone.
+If you use some of the tools in the project please consider donating or contributing on their projects. It doesn't have to be monetary, reporting bugs and PRs help improve the projects for everyone.

mkdocs.yml

@@ -1,9 +1,28 @@
 site_name: IOTstack
 site_description: 'Docker stack for getting started on IOT on the Raspberry PI'
+
+
+# Repository
+repo_url: https://github.com/SensorsIot/IOTstack
+repo_name: SensorsIot/IOTstack
+edit_uri: "https://github.com/SensorsIot/IOTstack/edit/master/"
+
 theme:
   name: material
+  palette:
+    - scheme: default
+      toggle:
+        icon: material/weather-sunny
+        name: Switch to dark mode
+    - scheme: slate
+      toggle:
+        icon: material/weather-night
+        name: Switch to light mode
   features:
     - tabs
   plugins:
     - search
-    - awsome-pages
+    - git-revision-date-localized
+markdown_extensions:
+  - admonition
+  - pymdownx.superfences