toolshed/docs.coopcloud.tech
toolshed/docs.coopcloud.tech
3
1
Fork 21
Code Issues 4 Pull Requests 1 Packages Releases Activity

Operators tutorial update #265

Closed
linnealovespie wants to merge 0 commits from linnealovespie/docs.coopcloud.tech:docs into main
pull from: linnealovespie/docs.coopcloud.tech:docs
merge into: toolshed:main
Conversation 7 Commits - Files Changed -
linnealovespie commented 2025-01-10 02:22:45 +00:00
First-time contributor
Copy Link

I was going through the operators tutorial as a relative beginner and found some areas that assumed things that I don't know. I made some edits to increase clarity.

I was going through the [operators tutorial](https://docs.coopcloud.tech/operators/tutorial/) as a relative beginner and found some areas that assumed things that I don't know. I made some edits to increase clarity.
🚀 1
linnealovespie added 1 commit 2025-01-10 02:22:45 +00:00
ammaratef45 reviewed 2025-01-10 02:57:54 +00:00
ammaratef45 left a comment
Member
Copy Link

Thank you so much for taking the time to do this, fresh perspective on documentation is always great!

Some of these belong to the toubleshoot - maybe we need error messages to point to that page and/or have the related section point to the details in the troubleshoot page to keep this page lean-ish

I also left some comments for discussion

Thank you so much for taking the time to do this, fresh perspective on documentation is always great! Some of these belong to the [toubleshoot](https://docs.coopcloud.tech/abra/trouble/#why-cant-abra-support-multiline-in-env-files) - maybe we need error messages to point to that page and/or have the related section point to the details in the troubleshoot page to keep this page lean-ish I also left some comments for discussion
docs/operators/tutorial.md Outdated
@ -30,6 +30,7 @@ You need to keep port `:80` and `:443` free on your server for web proxying to y
When running `usermod ...`, you may need to (depending on your system) log
in and out again of your shell session to get the required permissions for
Docker.
Alternatively you can run `newgrp` to register the group chnage.
ammaratef45 commented 2025-01-10 02:35:51 +00:00
Member
Copy Link

That's good to know, I read about newgrp and it's a handy command!

I would maybe add a link to the man page as well

That's good to know, I read about `newgrp` and it's a handy command! I would maybe add a link to the [man page](https://www.man7.org/linux/man-pages/man1/newgrp.1.html) as well
👍 1
docs/operators/tutorial.md Outdated
@ -56,0 +65,4 @@
```
docker run hello-world
```
ammaratef45 commented 2025-01-10 02:41:53 +00:00
Member
Copy Link

Would that require re-running the sudo usermod -aG docker $USER command too? I wonder if we can just add a sanity check earlier in the steps

<install docker>

# check docker group exists
groups | grep docker
# if docker groups doesn't exist run `sudo groupadd docker`
<rest of steps>
Would that require re-running the `sudo usermod -aG docker $USER` command too? I wonder if we can just add a sanity check earlier in the steps ``` <install docker> # check docker group exists groups | grep docker # if docker groups doesn't exist run `sudo groupadd docker` <rest of steps> ```
👍 1
docs/operators/tutorial.md
@ -68,6 +81,14 @@ Your entries in your DNS provider setup might look like the following.
Where `116.203.211.204` can be replaced with the IP address of your server.
On your local machine be sure to add your domain and all relevant subdomains in future steps to your `/etc/hosts` file. For example:
ammaratef45 commented 2025-01-10 02:50:44 +00:00
Member
Copy Link

This is a work around NAT hairpin - this is not an ideal solution however (though a quick way to test)

It's hard to document a solution that works for all network setups but we can document the problem and few possible solutions (including this one) in a section of the troubleshooting page

I'm happy to help working on that, I personally use my pihole to manage my local domains and avoid having to document these lines in the hosts files everytime I want to access the stack from an external network

This is a work around [NAT hairpin](https://superuser.com/questions/663820/port-forwarding-from-inner-network-to-inner-network-hairpin-nat) - this is not an ideal solution however (though a quick way to test) It's hard to document a solution that works for all network setups but we can document the problem and few possible solutions (including this one) in a section of the troubleshooting page I'm happy to help working on that, I personally use my pihole to manage my local domains and avoid having to document these lines in the hosts files everytime I want to access the stack from an external network
linnealovespie commented 2025-01-29 05:54:50 +00:00
Author
First-time contributor
Copy Link

A troubleshooting section sounds helpful, but if this is the quickest and easiest way around the NAT hairpin I might advocate that this stay more visible in the tutorial, with a callout that there are other ways to solve the issue in the troubleshooting section. As someone new to the concept of NAT hairpins entirely, I think it would be helpful for beginners to at least have a quick and dirty solution immediately available.

A troubleshooting section sounds helpful, but if this is the quickest and easiest way around the NAT hairpin I might advocate that this stay more visible in the tutorial, with a callout that there are other ways to solve the issue in the troubleshooting section. As someone new to the concept of NAT hairpins entirely, I think it would be helpful for beginners to at least have a quick and dirty solution immediately available.
docs/operators/tutorial.md Outdated
@ -198,6 +219,8 @@ DASHBOARD_ENABLED=false
**3. Now it is time to deploy your app:**
Ensure `<traefic-domain>` is registered in `/etc/hosts` then run:
ammaratef45 commented 2025-01-10 02:56:15 +00:00
Member
Copy Link

This can be replaced with Ensure <traefic-domain> is accessible or Ensure <traefic-domain> resolves to your server... tho I think the -D option is an exception to this rule

We should test it and see what's a more accurate statement to add here

This can be replaced with `Ensure <traefic-domain> is accessible` or `Ensure <traefic-domain> resolves to your server`... tho I think the `-D` option is an exception to this rule We should test it and see what's a more accurate statement to add here
linnealovespie commented 2025-01-29 05:55:59 +00:00
Author
First-time contributor
Copy Link

Formatting didn't resolve great, can you rephrase?

Formatting didn't resolve great, can you rephrase?
ammaratef45 commented 2025-02-03 01:35:52 +00:00
Member
Copy Link

my bad! corrected formatting

my bad! corrected formatting
docs/operators/tutorial.md Outdated
@ -220,3 +243,3 @@
Take care, these secrets are only shown once on the terminal so make sure to take note of them! `abra` makes use of the [Docker secrets](/operators/handbook/#managing-secret-data) mechanism to ship these secrets securely to the server and store them as encrypted data. Only the apps themselves have access to the values from here on, they're placed in `/run/secrets` on the container file system.
Then we can deploy Nextcloud:
Make sure` <nextcloud-domain>` is registered in `/etc/hosts`, then we can deploy Nextcloud:
ammaratef45 commented 2025-01-10 02:56:48 +00:00
Member
Copy Link

Same as my comment on the traefik-domain one

Same as my comment on the traefik-domain one
decentral1se reviewed 2025-01-10 10:16:05 +00:00
decentral1se left a comment
Owner
Copy Link

Woah, tysm @linnealovespie. I really can't overstate this enough: this is like one of the most valuable things you can do as a new person getting involved in the project, incredible work! Please don't hesitate to do more docs work 🙃 Nearly everyone I've spoken to involved in the project acknowledges the need to improve this part of the project. Hopefully see you around the matrix channels if you're keen for more!

Woah, tysm @linnealovespie. I really can't overstate this enough: this is like one of the most valuable things you can do as a new person getting involved in the project, incredible work! Please don't hesitate to do more docs work 🙃 Nearly everyone I've spoken to involved in the project acknowledges the need to improve this part of the project. Hopefully see you around the matrix channels if you're keen for more!
❤️ 1
docs/operators/tutorial.md Outdated
@ -139,3 +160,3 @@
And then:
abra server add -D example
`abra server add -D example`
decentral1se commented 2025-01-10 10:14:30 +00:00
Owner
Copy Link

Btw the -D from abra server add went away in the new release of abra (which is currently a release candidate but should go out soon-ish). See https://docs.coopcloud.tech/abra/upgrade/#09x-beta-010x-beta and specifically: toolshed/organising#631. Up to you, but maybe we can remove this -D while we're here?

Btw the `-D` from `abra server add` went away in the new release of `abra` (which is currently a release candidate but should go out soon-ish). See https://docs.coopcloud.tech/abra/upgrade/#09x-beta-010x-beta and specifically: https://git.coopcloud.tech/toolshed/organising/issues/631. Up to you, but maybe we can remove this `-D` while we're here?
👍 1
linnealovespie added 1 commit 2025-01-29 05:57:35 +00:00
decentral1se commented 2025-02-05 13:40:38 +00:00
Owner
Copy Link

Catching up on backlog of reviews 🤓

Please feel free to ping me when you want another pass!

Catching up on backlog of reviews 🤓 Please feel free to ping me when you want another pass!
decentral1se commented 2025-03-25 08:03:33 +00:00
Owner
Copy Link

@ammaratef45 @linnealovespie checking in again, any updates?

@ammaratef45 @linnealovespie checking in again, any updates?
ammaratef45 commented 2025-03-26 17:34:04 +00:00
Member
Copy Link

Aside from making the section for local network domains make sense (make it into a general solution to NAT hairpin problem) I have no problem with merging this

If it's okay with you @decentral1se and @linnealovespie can we remove this part for now and have an issue open for it? I don't have cycles for putting it together soon-ish

Aside from making the section for local network domains make sense (make it into a general solution to NAT hairpin problem) I have no problem with merging this If it's okay with you @decentral1se and @linnealovespie can we remove this part for now and have an issue open for it? I don't have cycles for putting it together soon-ish
decentral1se commented 2025-03-26 21:51:27 +00:00
Owner
Copy Link

@ammaratef45 @linnealovespie yeh go for whatever is handiest!

@ammaratef45 @linnealovespie yeh go for whatever is handiest!
ammaratef45 commented 2025-05-12 04:40:58 +00:00
Member
Copy Link

couldn't push to this branch so I created a new branch to merge, thanks @linnealovespie for the PR and @decentral1se for the feedback!

couldn't push to this branch so I created a new branch to merge, thanks @linnealovespie for the PR and @decentral1se for the feedback!
ammaratef45 closed this pull request 2025-05-12 04:40:58 +00:00

Pull request closed

Please reopen this pull request to perform a merge.
Sign in to join this conversation.
Reviewers
No Reviewers
Labels
No items
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
3wordchant abra-bot ammaratef45 Apfelwurm carla cas decentral1se fauno kawaiipunk knoflook lambdabundesverband moritz p4u1 simon trav val yksflip
No Assignees
3 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: toolshed/docs.coopcloud.tech#265
No description provided.
Delete Branch "linnealovespie/docs.coopcloud.tech:docs"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?