Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[MRG] Improve docs on Dockerfile escape hatch #1271

Open
wants to merge 4 commits into
base: main
Choose a base branch
from
Open

[MRG] Improve docs on Dockerfile escape hatch #1271

wants to merge 4 commits into from

Conversation

MattF-NSIDC
Copy link

I was struggling to find how to get the generated Dockerfile contents. When I found it, I thought I'd open a PR to add a link from the first place I looked for the next person who struggles :)

@mfisher87
Support Sphinx >=6.x
c2a3750 
sphinx-doc/sphinx#11094

`extlinks` config expects a formatting slug in the caption portion of
its config. Without it, Sphinx 6.x throws:

    Exception occurred:
      File "/path/to/site-packages/sphinx/ext/extlinks.py", line 103, in role
        title = caption % part
    TypeError: not all arguments converted during string formatting
@mfisher87
Add link from Dockerfile config file to debug usage
f610e1b
@welcome
Copy link

welcome bot commented May 18, 2023

Thanks for submitting your first pull request! You are awesome! 🤗

If you haven't done so already, check out Jupyter's Code of Conduct. Also, please make sure you followed the pull request template, as this will help us review your contribution more quickly.
welcome
You can meet the other Jovyans by joining our Discourse forum. There is also a intro thread there where you can stop by and say Hi! 👋

Welcome to the Jupyter community! 🎉

@mfisher87
Warn of unexpected behavior when creating a Dockerfile from debug output
e1ce6f5 
When creating a Dockerfile from redirecting debug output, `repo2docker`
sees the initially-empty `Dockerfile` and that influences its output
(since `Dockerfile` is empty, `repo2docker` outputs nothing).
@MattF-NSIDC
Copy link
Author

I experienced some unexpected behavior and added a warning to the docs ☝️

@MattF-NSIDC
Copy link
Author

I feel like more documentation is needed. When I create a Dockerfile following these instructions and attempt to build, there are errors because the Dockerfile references paths that aren't in the build context:

Step 26/60 : COPY --chown=1002:1002 build_script_files/-2fhome-2fmfisher-2f-2eminiconda3-2fenvs-2frepo2docker-2flib-2fpython3-2e11-2fsite-2dpackages-2frepo2docker-2fbuildpacks-2fconda-2factivate-2dconda-2esh-cf5cc0 /etc/profile.d/activate-conda.sh
COPY failed: file not found in build context or excluded by .dockerignore: stat build_script_files/-2fhome-2fmfisher-2f-2eminiconda3-2fenvs-2frepo2docker-2flib-2fpython3-2e11-2fsite-2dpackages-2frepo2docker-2fbuildpacks-2fconda-2factivate-2dconda-2esh-cf5cc0: file does not exist(repo2docker)

When I remove those steps, later steps fail because mamba and conda are both unavailable. What else can I do to document the process of switching from a non-Dockerfile config to a Dockerfile-based config?

@manics
Copy link
Member

manics commented May 18, 2023

The debug output is just for debugging, it's not intended to be buildable since you also need the full context that's created on the fly, and I don't think we should recommend it as a way to create a Dockerfile.

I've got a playground/proof-of-concept in https://github.com/manics/repo2shellscript if you're interested in seeing the full complexity.

@MattF-NSIDC MattF-NSIDC mentioned this pull request May 18, 2023
Closed
@MattF-NSIDC
Copy link
Author

Thanks @manics! Is there anything that can be documented about migrating from a config-file based build to a Dockerfile-based build? Does repo2docker provide any value add for that use case? I'm struggling with a build that has broken man pages, and I'm not seeing a repo2docker path to fixing it right now (since I think I need to do stuff as root to fix the issue).

@MattF-NSIDC
Copy link
Author

#700

@mfisher87
Correct my misunderstanding and add documentation that would have hel…
e4c2b41 
…ped past me

I did not see the "Can I use repo2docker to bootstrap my own
Dockerfile?" FAQ the first time through. I've linked it from the part
that I _did_ see so hopefully the next person through (maybe me in 6
months) won't have the same misunderstanding!
@MattF-NSIDC
Copy link
Author

Here's how I solved my problem: CryoInTheCloud/hub-image#65

As you know, I totally missed the "Can I use repo2docker to bootstrap my own Dockerfile?" FAQ on my first time through 😆 I've added a link to it where I would have seen it my first time through and replaced my bad suggestions with hopefully better ones, in addition to a new FAQ to resolve the specific problem with man pages.

MattF-NSIDC
MattF-NSIDC commented May 19, 2023
View reviewed changes
docs/source/config_files.rst

.. note::
If a Dockerfile is present, all other configuration files will be ignored.
With Dockerfiles, a regular Docker build will be performed. All other
configuration files will be ignored.
Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@manics I'd like to add a sentence here clarifying what value repo2docker is providing to the user in this case. e.g. All other configuration files will be ignored, but 'repo2docker' will still ___? Thoughts?

Thanks for your input on this change :)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers
No reviews
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

None yet
3 participants
@MattF-NSIDC @manics @mfisher87