[Idea]: Update readme

[funkytwig]

Describe the Feature/Enhancement/Idea

It might be good to add a section to the README with a simple 'HOWTO' explaining how to build the standard AMD64 and which Docker Compose file to use (dridged/defailt) for people who are not Docker experts. Additionally, perhaps we could use the Chromium Docker file.

Need to stress that you should build yourself, lots of YouTube videos around using standard Docker images.

I managed to work this out, and it was not difficult, but it took me a while.

Think this would be good for people who have used Docker Compose a bit (probably option to mention) but are not experts and just want to get it up and running.

Additional Context

No response

[funkytwig]

PS I could have a go at this but not sure about whether to use bridged, guess Chromium is the safest Docker file, maybe this should be the default?

[mbentley]

This is mostly covered under this section of the readme (https://github.com/mbentley/docker-omada-controller?tab=readme-ov-file#example-usage) but it doesn't reference the compose files, which would be easy enough to add. The tricky part is that the README is so massive at this point that it's almost becoming hard to find information. Maybe it's time to create a quickstart guide for those who really don't want to understand all of the nitty gritty details.

Host networking should be the default because it’s simple. The chromium image only works for amd64 and is only needed if people want to generate reports.

[funkytwig]

Yes, get the "The tricky part is that the README is so massive at this point that it's almost becoming hard to find information." bit. Was kind of thinking a bit at the beginning to give how-to type details at the beginning on how someone with a little Docker experience can get it up and running in a default environment (i.e. 5-15 WAPS, using docker-compose, maybe also docker command). Think this may help mitigate the length for a lot of people.

I got it working by simply using the amd64 build command from the README and the default Docker Compose file, so it's easy when you know how, but as you said, the README file is quite big (and a little intimidating). Also, maybe mention the https :8842 (think I remember correctly) is the URL to start with. Also, a passing reference to the Docker Chromium option. I also did a little digging on the bridged thing and came to the conclusion that the default one seems to do this, as it's the default for Docker (I think).

Regards, keep up the excellent work, Ben

[mbentley]

So I just took a quick stab at a Quickstart guide in this branch: https://github.com/mbentley/docker-omada-controller/tree/add-quickstart

Take a look and let me know if there are other topics that you think should be included.

[funkytwig]

Nice, great work.

So I did not need to build it myself, great.

Cople of small tweaks

In section 5 make slight changes

• docker compose - uses tag 5.15 as recommended and host mode networking, also recommended - a good place to start, but requires Docker Compose setting up
• docker run... - uses tag 5.15 as recommended and host mode networking, also recommended - a good place to start, just requires Docker to be set up
• k8s - if this does not mean anything to you, probably not what you want :)

[mbentley]

I appreciate the feedback - pushed another commit that added some sub-bullets that should address that and also a link to the Help section of the Discussions.

[funkytwig]

Cool, you thought of having a stable Docker tag. Or maybe not, as you should take a backup before going to a different version.

To be honest, I've not quite got my head around the full implications of using the latest, or some other tag that links to another tag (not even sure if stable is a thing), as it felt like upgrades happening without warning were risky. Not even sure if I can rely on things like the latest actually working reliably.

[mbentley]

For this, using latest is a bad idea just because it is possible that TP-Link might deprecate certain hardware at any given point in time. Typically they have done this during major version upgrades (3 to 4, or 4 to 5) but there is no policy I have seen that says they will not do it in a minor version bump, plus there might be unwanted changes in a given version. For software like this where I don't control it's development, the release notes become critical.

It's pretty safe when it comes to bugfix versions so that's where tags like 5.15 are ideal to use. Plus now that I am publishing GitHub releases, people can subscribe to those, read the release notes and make the version jump whenever they want.

I have very seriously considered removing the latest tag from this repo but I also understand some people want a set it and forget it experience. So I try my hardest to notify people by preventing the container from starting like I did when 4.x went to 5.x because that would have left everyone with broken controllers. I'm about to have to do something like that very soon though because Ubuntu 20.04 is end of life but you can't upgrade to a newer version of Ubuntu without also upgrading MongoDB which is a huge pain.

[mbentley]

I merged in the quickstart guide in here: #590