docs: update interactive environments documentation #1737

lorenzo-cavazzi · 2020-11-25T17:02:14Z

Update the Interactive Environments documentation pages, including the feature to pin images (that requires this to the merged SwissDataScienceCenter/renku-ui#1109).

fix #1647

rokroskar

This is great @lorenzo-cavazzi thanks!! Just a few minor comments. My future self (hunting for renku.ini options all over the docs) thanks you in advance 🙇

rokroskar · 2020-11-26T07:53:19Z

docs/user/interactive_basics.rst


-* auto-saving of work back to RenkuLab, so you can recover in the event of a
-  crash
+* Auto-saving of work back to RenkuLab, so you can recover in the event of a crash.


hmm this is not technically correct. We do not prevent loss of work if the infrastructure actually crashes.... I know it's not added in this PR but just a point to consider

Good point. We should mention a more generic "environment shutdown". We can also mention that environments are shut down automatically after 24h of inactivity

rokroskar · 2020-11-26T08:08:23Z

docs/user/interactive_basics.rst


-(This is defined in the project's ``.gitlab-ci.yml`` file.)
+This is defined in the project's :ref:`.gitlab-ci.yml file <gitlab_ci_yml>`. If the project


"this" could be taken to refer to "when any of the following happens" - which is not technically incorrect but maybe it's easier to say that the pipeline is defined:

Suggested change

This is defined in the project's :ref:`.gitlab-ci.yml file <gitlab_ci_yml>`. If the project

The pipeline is defined in the project's :ref:`.gitlab-ci.yml file <gitlab_ci_yml>`. If the project

rokroskar · 2020-11-26T08:10:11Z

docs/user/interactive_basics.rst


-(This is defined in the project's ``.gitlab-ci.yml`` file.)
+This is defined in the project's :ref:`.gitlab-ci.yml file <gitlab_ci_yml>`. If the project
+references a pinned image, the UI will not check for the image availability - that is


small wording change suggestion - and maybe we should link to the relevant section describing this option here?

Suggested change

references a pinned image, the UI will not check for the image availability - that is

references a specific image to use for all environments, the UI will not check for the image availability - that is

rokroskar · 2020-11-26T08:33:55Z

docs/user/interactive_customizing.rst

+the default ``Dockerfile`` provided in the template, the first line is a
+``RENKU_BASE_IMAGE`` argument used to feed the following ``FROM`` instruction.
+It specifies a
+`versioned base docker image <https://github.com/SwissDataScienceCenter/renku-jupyter>`_.


oops this link is wrong

Suggested change

`versioned base docker image <https://github.com/SwissDataScienceCenter/renku-jupyter>`_.

`versioned base docker image <https://github.com/SwissDataScienceCenter/renkulab-docker>`_.

rokroskar · 2020-11-26T21:22:49Z

docs/user/interactive_customizing.rst

+  Manually modifying the ``renku.ini`` file is not recommended.
+  You can use the
+  `renku config command <https://renku-python.readthedocs.io/en/latest/commands.html#module-renku.cli.config>`_
+  form an interactive environment.


Suggested change

form an interactive environment.

from an interactive environment, for example:

rokroskar · 2020-11-26T21:23:10Z

docs/user/interactive_customizing.rst

+
+.. note::
+
+  Manually modifying the ``renku.ini`` file is not recommended.


Oh really? That's the only way I ever do it 😄

ahah it may work for you, but I would say it's safer to use the renku command line to avoid messing up the config file 😁

I always just assume the UI is buggy and move on 😆

rokroskar · 2020-11-26T21:24:22Z

docs/user/interactive_customizing.rst

+
+    renku config set interactive.default_url "/tree"
+
+  We are working on adding a user friendly solution to set default options on


Suggested change

We are working on adding a user friendly solution to set default options on

We are working on adding a user-friendly solution to set default options on

👍
I'll fix it also on the other locations where we use the space

rokroskar · 2020-11-26T21:25:56Z

docs/user/interactive_customizing.rst

@@ -164,6 +174,58 @@ these base ``Dockerfile`` s and add the ``renku``, ``git``, and ``jupyter``
 parts to another base image that you might have.


+Renku project configurations


Maybe we can move this section before the Docker section? I imagine people might want to change this more often than they would want to dig into the Docker build itself.

lorenzo-cavazzi · 2020-11-30T10:19:51Z

Thanks for the review. All the points should be addressed.

ciyer

Lots of good improvements here. I think we need to be a bit clearer about the pinned image feature.

ciyer · 2020-12-01T08:20:00Z

docs/user/interactive_basics.rst

  language-specific dependency-management facilities (``requirements.txt``,
-  ``install.R``, etc.) or installed in the ``Dockerfile``
+  ``install.R``, etc.) or installed in the ``Dockerfile``.


We should add to this, I think.

* Any dependencies you specified via conda (``environment.yml``), using language-specific dependency-management facilities (``requirements.txt``, ``install.R``, etc.) or installed in the ``Dockerfile``. (An exception to this is if the project uses a pinned image. [See the section below](linked to pinned image section) for more information.)

@ciyer I thought we should try to avoid using the word "pinned" - I don't think it's really a term that most of our users understand immediately. But maybe it's more widely used than I think?

@rokroskar I wasn't involved with those discussions, so I don't know what arguments were presented.

I just do not find "custom" very descriptive in this case. There image isn't any more or less customized than any other image used in an interactive environment -- what is unique in this case is that the image if pinned/fixed and may not reflect the contents of the project (Dockerfile, environment.yml, etc.).

In fact, the project that was created for testing was called "fixed-image" -- that's an indication to me that there might be a naming mismatch.

@ciyer there wasn't really a discussion, it was just a suggestion I made here - I'm fine with using "pinned" but I thought we could maybe come up with something a bit less technical. If there isn't a better term then pinned is also OK.

It's custom in the sense that it's not the one automatically provided by the system. It might be one of our standard images, one that was built by a previous CI run, or something that the user created completely on their own.

ciyer · 2020-12-01T08:24:35Z

docs/user/interactive_customizing.rst

+over a short period of time (e.g. you use it in a presentation or a lecture).
+
+Even if it's common to start the environment with the default values, setting a default value
+doesn't prevent a user from changing it.


I do not think a user can change the pinned image, or am I wrong?

This is true in the current UI implementation, but I'm not sure if we want to change that or not.
The section is about all the options, but you are right, image is an exception. If you think it's better to specify it, I can add the text

I think we should describe the current UI behavior in the documentation. If that changes, then we should update the documentation.

lorenzo-cavazzi · 2020-12-02T14:03:46Z

I addressed the 2 points from the last review, but I didn't use the term pinned image.
@rokroskar @ciyer if we want to use a specific term (fixed/pinned/custom/ image) it's better to settle on a single one and keep it coherent both here in the docs and in the UI.

ciyer · 2020-12-02T16:36:38Z

I addressed the 2 points from the last review, but I didn't use the term pinned image.
@rokroskar @ciyer if we want to use a specific term (fixed/pinned/custom/ image) it's better to settle on a single one and keep it coherent both here in the docs and in the UI.

I have argued my point. In the end, it is @rokroskar 's decision.

rokroskar · 2020-12-02T21:27:57Z

@lorenzo-cavazzi I think go with "pinned" and if people respond with bewilderment we can revise :)

ciyer

👍

docs: update interactive environments documentation

6a0c028

fix #1647

lorenzo-cavazzi added this to the sprint-2020-11-13 milestone Nov 25, 2020

lorenzo-cavazzi requested a review from a team November 25, 2020 17:02

rokroskar requested changes Nov 26, 2020

View reviewed changes

docs: apply changes from the pr review

6842c68

rokroskar previously approved these changes Dec 1, 2020

View reviewed changes

ciyer requested changes Dec 1, 2020

View reviewed changes

docs: add other improvements from pr review

dd047d9

lorenzo-cavazzi dismissed rokroskar’s stale review via dd047d9 December 2, 2020 13:59

ciyer approved these changes Dec 4, 2020

View reviewed changes

ciyer mentioned this pull request Dec 4, 2020

custom images for interactive environments SwissDataScienceCenter/renku-ui#1109

Merged

lorenzo-cavazzi merged commit 550e6c9 into master Dec 4, 2020

lorenzo-cavazzi deleted the 1647-image-docs branch December 4, 2020 15:06

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: update interactive environments documentation #1737

docs: update interactive environments documentation #1737

lorenzo-cavazzi commented Nov 25, 2020

rokroskar left a comment •

edited

Loading

rokroskar Nov 26, 2020

lorenzo-cavazzi Nov 30, 2020

rokroskar Nov 26, 2020

rokroskar Nov 26, 2020

rokroskar Nov 26, 2020

rokroskar Nov 26, 2020

rokroskar Nov 26, 2020

lorenzo-cavazzi Nov 30, 2020

rokroskar Nov 30, 2020

rokroskar Nov 26, 2020

lorenzo-cavazzi Nov 30, 2020

rokroskar Nov 26, 2020

lorenzo-cavazzi commented Nov 30, 2020 •

edited

Loading

ciyer left a comment

ciyer Dec 1, 2020

rokroskar Dec 1, 2020

ciyer Dec 2, 2020

rokroskar Dec 2, 2020

ciyer Dec 1, 2020

lorenzo-cavazzi Dec 1, 2020

ciyer Dec 2, 2020

lorenzo-cavazzi commented Dec 2, 2020

ciyer commented Dec 2, 2020

rokroskar commented Dec 2, 2020

ciyer left a comment


		(This is defined in the project's ``.gitlab-ci.yml`` file.)
		This is defined in the project's :ref:`.gitlab-ci.yml file <gitlab_ci_yml>`. If the project

	This is defined in the project's :ref:`.gitlab-ci.yml file <gitlab_ci_yml>`. If the project
	The pipeline is defined in the project's :ref:`.gitlab-ci.yml file <gitlab_ci_yml>`. If the project

	references a pinned image, the UI will not check for the image availability - that is
	references a specific image to use for all environments, the UI will not check for the image availability - that is

	`versioned base docker image <https://github.com/SwissDataScienceCenter/renku-jupyter>`_.
	`versioned base docker image <https://github.com/SwissDataScienceCenter/renkulab-docker>`_.

	form an interactive environment.
	from an interactive environment, for example:


		.. note::

		Manually modifying the ``renku.ini`` file is not recommended.


		renku config set interactive.default_url "/tree"

		We are working on adding a user friendly solution to set default options on

	We are working on adding a user friendly solution to set default options on
	We are working on adding a user-friendly solution to set default options on

		@@ -164,6 +174,58 @@ these base ``Dockerfile`` s and add the ``renku``, ``git``, and ``jupyter``
		parts to another base image that you might have.


		Renku project configurations

docs: update interactive environments documentation #1737

docs: update interactive environments documentation #1737

Conversation

lorenzo-cavazzi commented Nov 25, 2020

rokroskar left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lorenzo-cavazzi commented Nov 30, 2020 • edited Loading

ciyer left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lorenzo-cavazzi commented Dec 2, 2020

ciyer commented Dec 2, 2020

rokroskar commented Dec 2, 2020

ciyer left a comment

Choose a reason for hiding this comment

rokroskar left a comment •

edited

Loading

lorenzo-cavazzi commented Nov 30, 2020 •

edited

Loading