starred/super

Fork 0

mirror of https://github.com/spr-networks/super.git synced 2026-04-24 20:35:55 +03:00

[GH-ISSUE #448] Missing documentation #225

New issue

Open

opened 2026-03-04 01:35:41 +03:00 by kerem · 4 comments

kerem commented

2026-03-04 01:35:41 +03:00

Owner

Originally created by @MrDrMcCoy on GitHub (Sep 29, 2025).
Original GitHub issue: https://github.com/spr-networks/super/issues/448

Originally assigned to: @lts-rad on GitHub.

Hello,

I'm a new customer that bought PLUS to support a deployment on my own hardware, and because you folks seem to be the ONLY group that makes a containerized managed network solution that can coexist with a regular Linux host environment.

However, I like to read docs before I dive face-first into things, and... there are some important things missing. This is intended to be constructive and to increase the appeal of your platform to others like me who may be confused as to whether your product meets our needs. Here is a list of the things that could be improved:

Most of the docs portray SPR deployments as single-device routing solutions, yet there are a few places where mesh functionality is mentioned. It would be great to have some indication of how to add APs to a deployment, if this is indeed a feature. The "manage devices" page is where I was hoping to find this, but it only covers client devices, not additional network devices. If it's the same full-fat deployment on all devices that later join together, then this is especially important to document; as they seem likely to want to set themselves up with the same IP and mDNS records. If this is intrinsically tied to the mesh functionality, that could be made much clearer, in addition to the actual process for setting up more than one device.
1.1 It's especially unclear if a wired-only "control" router can set up WiFi APs, which is not too uncommon of a config for SoHo deployments. I worry that the main router I am planning to set up, which lacks a WiFi card and is positioned where one would be useless, won't be able to drive my APs for lack of WiFi hardware to configure of its own.
When signing up for PLUS, I am told there is supposed to be a code to use in the software to activate features like mesh networking. I don't see anywhere in the Stripe receipts or main website on where to find this code. If that's something that your team needs to generate and send out manually, that's fine, but should be clearly be communicated.
There is not a lot in the contributor guide for how to actually contribute. I'm not a Go dev myself, but I have extensive sysadmin/SRE experience and would certainly consider contributing docs for additional deployment strategies, which may be of interest to the community. Perhaps a community Wiki could fill this role? I personally don't consider Discord to be a useful resource, as long-form information doesn't fit well there, nor is it particularly discoverable. The GitHub Discussions might better serve this role, but it's just crickets in there and is not linked to from the website, so it isn't clear anything posted there would ever be seen.
The docs are pretty tightly geared towards Docker on Ubuntu and/or Raspberry Pi. While it's unreasonable to support every platform, the docs could be made a bit more distro and runtime agnostic by steering away from automated scripts and including Podman as a suggested container engine (which has many benefits). I would be willing to contribute docs for this once I have my deployment running and some guidance on how to contribute docs.

A few more that bleed into feature requests a bit:

Running on a distributed container orchestrator like K8s, Nomad, etc would be an attractive feature that would drive you up in the search rankings. That is a large ask, but is also an area where I would be interested in contributing docs.
Expand the docs to cover relieving the pain points of requiring per-device WiFi. Having guests over and supporting a large number of devices in a shared household (as is the case for me) is quite tedious with this requirement, and this likely drives people away without some guidance on how to make it less frustrating. Even though it weakens security posture slightly, being able to disable such a requirement would be very welcome, and not being able to really needs to be sold regarding the cost of maintenance versus security.
While VPN server and site-to-site functionality are covered, nothing is mentioned for public VPN client support. If this is not yet supported, it is popular enough for this to be worth calling out any future plans. If it is supported already, saying so makes the platform more attractive! Especially so if you can set up multiple for failover, and require some or all devices to route through them ;-) .

Thanks for making this! I hope to be useful in some way to the project once I get it running.

Originally created by @MrDrMcCoy on GitHub (Sep 29, 2025). Original GitHub issue: https://github.com/spr-networks/super/issues/448 Originally assigned to: @lts-rad on GitHub. Hello, I'm a new customer that bought PLUS to support a deployment on my own hardware, and because you folks seem to be the ONLY group that makes a containerized managed network solution that can coexist with a regular Linux host environment. However, I like to read docs before I dive face-first into things, and... there are some important things missing. This is intended to be constructive and to increase the appeal of your platform to others like me who may be confused as to whether your product meets our needs. Here is a list of the things that could be improved: 1. Most of the docs portray SPR deployments as single-device routing solutions, yet there are a few places where mesh functionality is mentioned. It would be great to have some indication of how to add APs to a deployment, if this is indeed a feature. The "manage devices" page is where I was hoping to find this, but it only covers client devices, not additional network devices. If it's the same full-fat deployment on all devices that later join together, then this is especially important to document; as they seem likely to want to set themselves up with the same IP and mDNS records. If this is intrinsically tied to the mesh functionality, that could be made much clearer, in addition to the actual process for setting up more than one device. 1.1 It's especially unclear if a wired-only "control" router can set up WiFi APs, which is not too uncommon of a config for SoHo deployments. I worry that the main router I am planning to set up, which lacks a WiFi card and is positioned where one would be useless, won't be able to drive my APs for lack of WiFi hardware to configure of its own. 2. When signing up for PLUS, I am told there is supposed to be a code to use in the software to activate features like mesh networking. I don't see anywhere in the Stripe receipts or main website on where to find this code. If that's something that your team needs to generate and send out manually, that's fine, but should be clearly be communicated. 3. There is not a lot in the contributor guide for how to actually contribute. I'm not a Go dev myself, but I have extensive sysadmin/SRE experience and would certainly consider contributing docs for additional deployment strategies, which may be of interest to the community. Perhaps a community Wiki could fill this role? I personally don't consider Discord to be a useful resource, as long-form information doesn't fit well there, nor is it particularly discoverable. The GitHub Discussions might better serve this role, but it's just crickets in there and is not linked to from the website, so it isn't clear anything posted there would ever be seen. 4. The docs are pretty tightly geared towards Docker on Ubuntu and/or Raspberry Pi. While it's unreasonable to support every platform, the docs could be made a bit more distro and runtime agnostic by steering away from automated scripts and including Podman as a suggested container engine (which has many benefits). I would be willing to contribute docs for this once I have my deployment running and some guidance on how to contribute docs. A few more that bleed into feature requests a bit: 5. Running on a distributed container orchestrator like K8s, Nomad, etc would be an attractive feature that would drive you up in the search rankings. That is a large ask, but is also an area where I would be interested in contributing docs. 6. Expand the docs to cover relieving the pain points of requiring per-device WiFi. Having guests over and supporting a large number of devices in a shared household (as is the case for me) is quite tedious with this requirement, and this likely drives people away without some guidance on how to make it less frustrating. Even though it weakens security posture slightly, being able to disable such a requirement would be very welcome, and not being able to really needs to be sold regarding the cost of maintenance versus security. 7. While VPN server and site-to-site functionality are covered, nothing is mentioned for public VPN client support. If this is not yet supported, it is popular enough for this to be worth calling out any future plans. If it is supported already, saying so makes the platform more attractive! Especially so if you can set up multiple for failover, and require some or all devices to route through them ;-) . Thanks for making this! I hope to be useful in some way to the project once I get it running.

kerem added the

enhancement

documentation

labels

2026-03-04 01:35:41 +03:00

kerem commented

2026-03-04 01:35:42 +03:00

Author

Owner

@lts-rad commented on GitHub (Sep 29, 2025):

Excellent feedback, let me check what's happened with the PLUS code, an e-mail should have been sent out once stripe processed with instructions for how to set up Mesh.

@lts-rad commented on GitHub (Sep 29, 2025): Excellent feedback, let me check what's happened with the PLUS code, an e-mail should have been sent out once stripe processed with instructions for how to set up Mesh.

kerem commented

2026-03-04 01:35:42 +03:00

Author

Owner

@lts-rad commented on GitHub (Sep 29, 2025):

Please let me know if you have received an e-mail now.

Do you have a preferred wiki? What would you think of Discourse (https://www.discourse.org/) ?

The PLUS guide is a bit buried, i'll move it out to the side bar, it walks through how to activate and there's a link for the mesh setup there as well
https://www.supernetworks.org/pages/docs/guides/guides_plus/plus

@lts-rad commented on GitHub (Sep 29, 2025): Please let me know if you have received an e-mail now. Do you have a preferred wiki? What would you think of Discourse (https://www.discourse.org/) ? The PLUS guide is a bit buried, i'll move it out to the side bar, it walks through how to activate and there's a link for the mesh setup there as well https://www.supernetworks.org/pages/docs/guides/guides_plus/plus

kerem commented

2026-03-04 01:35:42 +03:00

Author

Owner

@MrDrMcCoy commented on GitHub (Sep 29, 2025):

Hi @lts-rad ,

Looks like I got the email with the code this morning just a little before your reply, so thanks for pushing it through!

In the past, I've liked Xwiki for being both feature-rich and easy to use. I've also had my eye on Outline and Docmost for a while now, and they can all be freely self-hosted.

Regarding Discourse, I think it is probably the best traditional forum engine currently out there, but their default layout and theme always rubbed me the wrong way. Shouldn't be hard to fix, I'm sure that's easily configurable.

As for the PLUS guide, I did read through that before I posted here. It is just a stub in my opinion, as the process for setting up another SPR node is not described in any detail. After digging through the config generator scripts, it does appear that you can configure the IP that SPR will start with so as to avoid IP conflicts, but it's still not entirely clear whether I'm doing full deployments on each device and joining them together later, or if there's some other procedure that needs to be followed. I plan to see how far I can get later this evening.

@MrDrMcCoy commented on GitHub (Sep 29, 2025): Hi @lts-rad , Looks like I got the email with the code this morning just a little before your reply, so thanks for pushing it through! In the past, I've liked [Xwiki](https://xwiki.com/) for being both feature-rich and easy to use. I've also had my eye on [Outline](https://www.getoutline.com) and [Docmost](https://docmost.com) for a while now, and they can all be freely self-hosted. Regarding Discourse, I think it is probably the best traditional forum engine currently out there, but their default layout and theme always rubbed me the wrong way. Shouldn't be hard to fix, I'm sure that's easily configurable. As for the PLUS guide, I did read through that before I posted here. It is just a stub in my opinion, as the process for setting up another SPR node is not described in any detail. After digging through the config generator scripts, it does appear that you can configure the IP that SPR will start with so as to avoid IP conflicts, but it's still not entirely clear whether I'm doing full deployments on each device and joining them together later, or if there's some other procedure that needs to be followed. I plan to see how far I can get later this evening.

kerem commented

2026-03-04 01:35:42 +03:00

Author

Owner

@lts-rad commented on GitHub (Sep 29, 2025):

Thank you. I will take a look at those. I kind of agree about discourse UI theres a lot of empty space visually and too much gamification, perhaps.

For the IP setup that is definitely a pain point. There's a lot to cover in this ticket so i am opening a [new ticket] on this mesh setup pain with the IP (https://github.com/spr-networks/super/issues/450) to track.

@lts-rad commented on GitHub (Sep 29, 2025): Thank you. I will take a look at those. I kind of agree about discourse UI theres a lot of empty space visually and too much gamification, perhaps. For the IP setup that is definitely a pain point. There's a lot to cover in this ticket so i am opening a [new ticket] on this mesh setup pain with the IP (https://github.com/spr-networks/super/issues/450) to track.

kerem referenced this issue

2026-03-04 01:36:33 +03:00

[PR #225] [MERGED] Gstack #379