Guidelines on opening HTTP/HTTPS ports

[jayaddison]

Is your feature request related to a problem? Please describe.
As reported in grocy/grocy-docker#95, some additional steps are required in order to make a containerized grocy application public.

That's a good thing in some ways; making the application public should be an intentional, informed decision, and we should ensure that users cannot accidentally expose their instance to the public, especially with a default password.

Although the ultimate goal for this issue is to document opening HTTP/HTTPS ports safely, I reckon there are a few dependencies before we can write updated documentation. Even so, I'd like to open an issue here to track progress.

Ideally I'd suggest that these tasks might be required to make setup as straightforward and safe as possible:

• Allow / require the system operator to provide a strong admin password during first-setup ( see Request: Stronger initial login credentials grocy-docker#206 )
• Enable an automated containerized-TLS setup workflow via LetsEncrypt ( see Enable certificate provisioning via letsencrypt grocy-docker#62 )
• Provide a manual containerized-TLS setup workflow where a user supplies certificate material of their own to the grocy container (todo: how?)
• Update the container setup tutorial to explain the options available to users and how to safely make their grocy install public

Describe the solution you'd like
Hopefully the tasks above outline a potential, gradual solution. I'd be very glad for feedback on whether these seem sensible and whether any steps/tasks could be missing.

Describe alternatives you've considered
We could provide guidance around very specific workflows and code/config file changes required to rebuild containers with custom credentials/certificates.

In my opinion these wouldn't be ideal; I think it's better to do the additional work to require a strong setup-time password and support TLS, and only provide documentation once these features are ready and can be supported.

[kses]

I agree that onboarding new users is hard. Big part of it what kind of it is that you know nothing of their experience, existing setup and hardware (or if they plan to run it on AWS or similar). Doing it via a raspberry pi and home assistant is dead simple though. You do not need to use the terminal. It solves all of the dependancies and you can, if you do not wish to setup your own reverse proxy and dynamic dns pay a few usd a month to use their nabu casa web soluton.

I know the setup tutorial is very bare bones, I thought that it would be better than nothing at least and collecting some of the links needed to get started. It needs more love though. Never thought anyone would try to setup Grocy on AWS following the tutorial, it was written with the assumption that the person going through it was running it on a local machine.

I have not played much with the official docker image, I do not really know what kind of lets encrypt support it provides, but another way forward could be a that the is to run openvpn instead of exposing Grocy directly.

All help is appreciated! I think grocy deserves more and better documentation.

I have planned to start a VM just for doing a good step by step tutorial, but have not decided of which operating system that should run etc.

[jayaddison]

Thanks @kses - yep, I agree completely with the idea of keeping the process as simple as possible for small / enthusiast installs.

I tried to avoid using the word 'terminal' anywhere in the suggestions above, because I do believe that a graphical user interface of some kind - likely web-based - could be the easiest setup experience, particularly because it would be most consistent with the rest of the grocy user interface.

I also don't think we should aim specifically for one particular cloud (or even operating system) platform; those may change over the next few years as they have over the past.

I'll hope to chip away at (and/or review other approaches) to the tasks above, although I can't really offer a timescale. It'll be in a way that aims to avoid any problems for introductory-level users.

NB: It'd require more investigation, but from what I've seen/heard, wireguard may be a more modern -- and easier to use -- substitute for openvpn.

[kses]

Do you know if anyone are actively working a graphical on boarding process?

I think that at the moment a detailed setup by step guide based on for example a clean install of Ubuntu server or raspbian is the best I can do. It would require terminal use and changes to configuration files. I think that is knowledge that you need to acquire when you use a smaller open source project. I do not have the skills required to contribute in any meaningful way to the actual project.

[jayaddison]

Thanks @kses - yep, documenting the terminal-based setup has already been extremely helpful.

I should clarify that the web onboarding I'm suggesting would be after those terminal commands are completed, but before the user logs into grocy for the first time. It'd be like a set of 'intro' pages that appear in the browser on first-load, and would walk the user through entry/generation of a strong password (and perhaps any other essential setup-time configuration).

I don't know anyone working on this currently, but I've done a little PHP in the past, so I might try to offer something in future (and of course, this being open source, anyone can offer the same before then if they feel like it :))

[gersilex]

which operating system that should run

As we already have a Windows App, I think we can skip Windows completely.

For the Linux Operating system, I'd choose the Distribution that is most widely used and based on the most widely supported Distribution: Ubuntu

I've highlighted Debian-based Distributions in yellow.

I am very proficient with Linux and like Debian and Ubuntu the least, but that's only because I've grown out of it. Ubuntu is so great for getting started with it and even many commercial products that support Linux only actively support the Ubuntu Distribution, and we should do that as well.

Advanced or professional users will always choose Containers on their favorite distributions and they will know how to do it, so we don't need to cover them in our docs.

[kses]

So aiming for Ubuntu, I would think docker is the easiest way to get going.

Running the official container, how easy is it to setup TLS (I am running the Linuxserver version)? Or is some other kind of access more suitable, such as VPN with key?

[LukeStaszewski]

Hello all,

Bit of a docker newbie here but I'd like to try and help if at all possible. I've been trying to setup Grocy on my dedicated server using Docker but having some issues that I believe are related to this issue.

I've setup a few similar applications (Wordpress, Wikijs etc) and for that I used https://github.com/nginx-proxy/nginx-proxy

It makes it very easy to do so, you just setup the nginx-proxy in a container, create a network and expose it to the network.

Then you connect all the apps you want to run through nginx to the same network in docker and just add in the environent variables like so:

  VIRTUAL_HOST: sub.domain.com
  VIRTUAL_NETWORK: nginx-proxy
  VIRTUAL_PORT: 3000
  LETSENCRYPT_HOST: sub.domain.com
  LETSENCRYPT_EMAIL: your@email.com

and then it does all the work for you, routes to the correct app, installs and renews certificates, reloads containers when changes are made etc.

Perhaps this will help with what you are trying to achieve?

I tried to edit the grocy docker github to use this but I am not sure where to start. I think I need to learn some more about dockerfiles, as with my previous installations (wikijs, wordpress etc) there was no need to use dockerfiles (at least manually on my end).

[kses]

This is my current plan for extened install docs (docker only). Do you think it is the correct way forward or should the recommended install process be something else?

Pre-req

• Ubuntu Desktop LTS or server LTS
• 10 most common terminal commands and tools (cd, ls, apt-get, sudo, rel/abs paths, nano)
• git install
• docker and docker compose install
• any extra dependencies that might be needed.

2 Min install

• Gorcys offical docker on local machine.
• Give a tip about VPN.

Extended install

Exposing Grocy to the world:

• Require/Assume you have your own domain.
• (migrating from 2min install instructions)
• linux server grocy image
• portainer
• linuxserver duckdns image
• linuxserver letsencrypt nginx image

[johnhkchen]

Just as an update, now you can run a command as simple as:

tailscale serve --bg http://127.0.0.1:8080

To provision the HTTPS necessary to get Grocy out on the internet