nebari-dev / nebari-dev/nebari-docs

[BUG] - Local deployment guide around domains could be improved

Open
#403 0 comments 2 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

needs: PR 📬 type: bug 🐛
Dominant language
No language data
Stars
21
Forks
40
Avg merge
19h 50m
Merged PRs (30d)
6

Description

Describe the bug

In the local deployment documentation (https://www.nebari.dev/docs/how-tos/nebari-local/) the following entry for /etc/hosts is recommended:

172.18.1.100 <domain>

There are two issues I found with it:

  • the <> syntax appears to indicate that one should substitute the variable; I found this confusing because the earlier command (nebari init local --project projectname --domain domain) did not use such indicator for parts which should be substituted
  • in stage three of the deployment a slightly different IP was assigned for me (172.19.1.100) which lead to the following failure:
    [terraform]: load_balancer_address = {
    [terraform]:   "hostname" = ""
    [terraform]:   "ip" = "172.19.1.100"
    [terraform]: }
    Attempt 1 succeeded to connect to tcp://172.19.1.100:80
    Attempt 1 succeeded to connect to tcp://172.19.1.100:8786
    Attempt 1 succeeded to connect to tcp://172.19.1.100:8022
    Attempt 1 succeeded to connect to tcp://172.19.1.100:8023
    Attempt 1 succeeded to connect to tcp://172.19.1.100:9080
    Attempt 1 succeeded to connect to tcp://172.19.1.100:443
    After stage=04-kubernetes-ingress kubernetes ingress available on tcp ports={80, 8786, 8022, 8023, 9080, 443}
    Attempt 1 polling DNS domain=domain does not match ip=172.19.1.100 instead got ['172.18.1.100']
    Attempt 2 polling DNS domain=domain does not match ip=172.19.1.100 instead got ['172.18.1.100']
    [... deplyment hangs on DNS polling ... ]
    
Expected behavior

I would kindly suggest that either <> is explained and used consistently in all examples (I see that it is also used for email address in let's encrypt example, but nowhere else), or a more self-explanatory domain name is used in the guide, e.g.:

nebari init local --project projectname --domain yourdomainname
# in /etc/hosts
172.18.1.100   yourdomainname

Also, it would greatly help if the guide mentioned that a different IP address might be chosen during deployment, and where to find it.

How to Reproduce the problem?

Follow the local deployment guide

Command output

No response

Versions and dependencies used.
  • Ubuntu 23.10
  • nebari --version 2024.1.1
Anything else?

No response

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the local deployment guide at https://www.nebari.dev/docs/how-tos/nebari-local/ and compare its nebari init command with the /etc/hosts example. Verify how the deployment reports the assigned IP, then update the guide to explain placeholder syntax and account for a different deployment IP; the examples and DNS polling guidance should be consistent.

Written by the indexing model from the issue text.

Assessment

Tech stack
kubernetes, terraform, ubuntu
Domain
devops, documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.