I just spent 2.5 hours fumbling around the OwnTracks documentation trying to install via Docker. The booklet only has installation instructions using the Quicksetup tool. This is only useful if the system it's running on does not utilize containers. Most homelab servers nowadays are running TrueNAS, unRAID, or some other Unix-based OS that runs Docker containers. I was able to find in the Recorder's README that there is a Docker image documented in the Booklet. Going to the booklet link shown there (which btw, doesn't even show up in the Booklet's table of contents!), it redirects me again to the docker-recorder repo. Not a huge deal, but now there's three places I have to read from - the Recorder README, the docker-recorder README, and the Booklet. Ideally, this should all just be in the Booklet, and the READMEs are just for us devs to understand how to build/test each system.
Then there's the rabbit hole of TLS over MQTT. The Docker docs briefly introduce the idea, but don't provide any links. The Recorder's README provides no useful information. I don't even know how, but I eventually found the TLS Booklet page on setting up TLS, which is entirely missing from the table of contents. This page also has broken image links that just have an alt text of Android or iOS. This makes references to StartSSL, which is now defunct. Throughout this entire page, no commands are present. I'm not a TLS expert, and the documentation shouldn't assume so. I don't know how to generate certs off the top of my head. This page does link to this tlscert page, which tells you to use a script from an archived Tools Repository. This script will not run without errors. I had to clear some of the blank %%% lines around line 177. Then it finally runs, but the documentation straight up abandons you and doesn't tell you what to do with the new certs. I managed to figure out which files to use on my own after much trial-and-error.
tl;dr: I don't like swimming through docs to find pieces of setup documentation. There should just be an "Installation" section in the Booklet with Quicksetup, Docker, reverse proxy, HTTP/MQTT etc.
To be clear, I love this project. This is a really cool idea, and a great alternative to apps like Life360. I really want to get this working for my family. However, if the documentation assumes you already know everything about the project and its subjects, it makes setup extremely difficult for newcomers like myself.
I think I'll tackle this problem myself as I'm still trying to understand how the system works so I can get it setup. I'm running Docker behind Nginx Proxy Manager, so I'll be able to contribute setup instructions there at the very least.
I just spent 2.5 hours fumbling around the OwnTracks documentation trying to install via Docker. The booklet only has installation instructions using the Quicksetup tool. This is only useful if the system it's running on does not utilize containers. Most homelab servers nowadays are running TrueNAS, unRAID, or some other Unix-based OS that runs Docker containers. I was able to find in the Recorder's README that there is a Docker image documented in the Booklet. Going to the booklet link shown there (which btw, doesn't even show up in the Booklet's table of contents!), it redirects me again to the docker-recorder repo. Not a huge deal, but now there's three places I have to read from - the Recorder README, the docker-recorder README, and the Booklet. Ideally, this should all just be in the Booklet, and the READMEs are just for us devs to understand how to build/test each system.
Then there's the rabbit hole of TLS over MQTT. The Docker docs briefly introduce the idea, but don't provide any links. The Recorder's README provides no useful information. I don't even know how, but I eventually found the TLS Booklet page on setting up TLS, which is entirely missing from the table of contents. This page also has broken image links that just have an alt text of
AndroidoriOS. This makes references to StartSSL, which is now defunct. Throughout this entire page, no commands are present. I'm not a TLS expert, and the documentation shouldn't assume so. I don't know how to generate certs off the top of my head. This page does link to this tlscert page, which tells you to use a script from an archived Tools Repository. This script will not run without errors. I had to clear some of the blank%%%lines around line 177. Then it finally runs, but the documentation straight up abandons you and doesn't tell you what to do with the new certs. I managed to figure out which files to use on my own after much trial-and-error.tl;dr: I don't like swimming through docs to find pieces of setup documentation. There should just be an "Installation" section in the Booklet with Quicksetup, Docker, reverse proxy, HTTP/MQTT etc.
To be clear, I love this project. This is a really cool idea, and a great alternative to apps like Life360. I really want to get this working for my family. However, if the documentation assumes you already know everything about the project and its subjects, it makes setup extremely difficult for newcomers like myself.
I think I'll tackle this problem myself as I'm still trying to understand how the system works so I can get it setup. I'm running Docker behind Nginx Proxy Manager, so I'll be able to contribute setup instructions there at the very least.