Uploaded image for project: 'Jenkins Website'
  1. Jenkins Website
  2. WEBSITE-466

Interactive Tutorial proposal from "Post FOSDEM 2018 Jenkins Hackfest"

    Details

    • Type: New Feature
    • Status: To Do (View Workflow)
    • Priority: Minor
    • Resolution: Unresolved
    • Component/s: content
    • Labels:
      None
    • Similar Issues:

      Description

      This issue is to keep track of the activity on this topic (Katacoda tutorial integration) during the the "Post FOSDEM 2018 Jenkins Hackfest" (https://www.meetup.com/fr-FR/jenkinsmeetup/events/246098584/).

      Goal of the contribution

      The tutorial "Build a Java app with Maven" (https://jenkins.io/doc/tutorials/build-a-java-app-with-maven/ ) is a great one for starters.
      However, the time (20 - 40 min) and requirements needed to complete it are cumbersome.
      Also, there is a lot of moving parts here (Docker, GitHub, Copy & Paste from the web browser) that can make the tutorial not working or difficult to maintain.

      We want to propose to update this tutorial content using a KataCoda (https://www.katacoda.com/) course, that will provide step by step instructions along with an online sandbox environment (no need to run jenkins locally).

      We want to provide a PR with a working Proof Of Concept that can be discussed ("What it looks like?", "What are the corner cases/risks using KataCoda?", "Is this tutorial the right one to feature this kind of integration?", etc.).

      Last goal is to provide an example of contribution to newcomers to the project.

      Contributors

      During the Hackfest, we were 4 people working on this: Adolfo Solero , Olivier Vernin, xuefeng shi and myself.

      Tutorial Audit

      Current flow

      The current tutorial follows the main steps:

      1. Requirements
      2. Starting Jenkins using Docker
      3. Forking the repository on GitHub and cloning it locally
      4. Access and Configure Jenkins using the "First Time" Wizard
      5. Create a Pipeline Job in the Classic UI
      6. Add a Jenkinsfile in the git repository, and commit
      7. Run the pipeline and see it running in Blue Ocean
      8. Iterate 3 times until you have a 3 steps "Build -> Test -> Deploy" Pipeline

      What to keep or throw away

      We wanted to put boundaries on our work, based on paint points and gain from
      KataCoda, compared to the current tutorial:

      1. Should be kept outside KataCoda, and simplified (HTML5 webbrowser and WebSockets support)
      2. This section can be deleted: KataCoda will take care of this
      3. Discussion about the constraints of using GitHub (account to create, not able to reach in China or some companies, adding addition complexity to the tutorial), versus the advantages (tracking of forks, it provides a platform we don't have to maintain, having an upstream project allow fixed behaviours)

      • Consensus to not bother the end user with GitHub

      4. Discussion about pros and cons of having the Wizard versus a pre-configured Jenkins instance.

      5. We keep it as it is today: we don't want to cover the topic "Use the Blue Ocean experience for creating a Pipeline"
      6. We would want to validate if we can use the KataCoda's integrated IDE to provide a fixed environment.
      7. Keep it as it is today.
      8. Keep it as it is today.

      Implementation

      • Olivier Vernin is currently owning the main repository containing the KataCoda scenario: https://github.com/olblak/katacoda
        • We do Pull Requests against this repository
        • It will be discussed here to see the next step if accepted (move the repo to jenkins(.*) GitHub organizations, or move content on jenkins.io repository, or even something else)
      • Each one of use configure our KataCoda profile to point to our fork of this repository. Olivier Vernin points to the main repository:
      • We fill the KataCoda scenario steps by picking the current asciidoctor source from https://github.com/jenkins-infra/jenkins.io/blob/master/content/doc/tutorials/build-a-java-app-with-maven.adoc
        • It is MarkDown: we have to convert from asciidoctor
        • We split the Steps by the current chapters (defined in "index.json")
      • The "sandbox" is providing 2 services using Docker backend in KataCoda (for each trainee):
        • A pre-configured Jenkins instance
        • The sources for the Docker Images will be stored inside the same repository as the scenario, so it can be build by an external CI process and hosted on the public DockerHub (mirrored in China)
          • For the hackday, we will build and push manually the image as a first exploratory step

      Task List

      • Create a main repository to work on Olivier Vernin
      • Initialize a base KataCoda Training with the same name as the jenkins.io website Olivier Vernin
      • Validate what to keep/throw for the first iteration
      • Report Issue and ask someone else for external advice
      • Rework the content to fit the training after the hackday
      • Open a PR to WebSite to propose integration in the website
      • Implement a CI/CD docker build for the images used (CodeValet?)
      • Move the repository to the JenkinsCi organization if approved
      • Move the Docker Images JenkinsCi organization if approved

        Attachments

          Activity

          Hide
          ggaskell Giles Gaskell added a comment - - edited

          This looks good Damien Duportal

          Just a couple of points to add about these tutorials:

          • If you're planning to run through multiple tutorials from this page, the Run Jenkins in Docker section on any given tutorial only needs to be performed once. Hence, if you're running through one of these tutorials for the first time, you can skip the Run Jenkins in Docker section in other tutorials. This is mentioned at the end of each tutorial's introductory section (in the paragraph just before Prerequisites), although I guess it might be easy to miss. FYI, the Asciidoc source for each tutorial page (so far) re-uses the same Run Jenkins in Docker content (as an Asciidoc inclusion).
          • The reason I designed these tutorials this way is that I wanted them to target users (especially those of the OSS community) who are new to Jenkins and want to quickly get an instance up and running on their own computer so they can see how Jenkins is meant to work. Having said that, if there were an option of an already-running (perhaps cloud-based) Jenkins instance that the OSS community could access relatively easily, then I probably would have written these tutorials differently. By no means is the current wording of these tutorials set in stone (they've evolved significantly over the last 6 months).
          • I've deliberately kept the Run Jenkins in Docker content deliberately separate from the content in the Docker section of the Installing Jenkins page. This is because the Installing Jenkins content contains a lot more information and my intent was to minimize overloading readers of the tutorial with too much information.

          Anyway, I'm keen to see how the proposals above transpire!

          Show
          ggaskell Giles Gaskell added a comment - - edited This looks good Damien Duportal Just a couple of points to add about these tutorials : If you're planning to run through multiple tutorials from this page, the Run Jenkins in Docker section on any given tutorial only needs to be performed once. Hence, if you're running through one of these tutorials for the first time, you can skip the Run Jenkins in Docker section in other tutorials. This is mentioned at the end of each tutorial's introductory section (in the paragraph just before Prerequisites ), although I guess it might be easy to miss. FYI, the Asciidoc source for each tutorial page (so far) re-uses the same Run Jenkins in Docker content (as an Asciidoc inclusion). The reason I designed these tutorials this way is that I wanted them to target users (especially those of the OSS community) who are new to Jenkins and want to quickly get an instance up and running on their own computer so they can see how Jenkins is meant to work. Having said that, if there were an option of an already-running (perhaps cloud-based) Jenkins instance that the OSS community could access relatively easily, then I probably would have written these tutorials differently. By no means is the current wording of these tutorials set in stone (they've evolved significantly over the last 6 months). I've deliberately kept the Run Jenkins in Docker content deliberately separate from the content in the Docker section of the Installing Jenkins page . This is because the Installing Jenkins content contains a lot more information and my intent was to minimize overloading readers of the tutorial with too much information. Anyway, I'm keen to see how the proposals above transpire!
          Hide
          ggaskell Giles Gaskell added a comment -

          Btw ... very minor point, in the Tutorial Audit > Content Flow (above), I believe 3 and 4 should be switched around (as 4 is meant to follow directly on from 2).

          Show
          ggaskell Giles Gaskell added a comment - Btw ... very minor point, in the Tutorial Audit > Content Flow (above), I believe 3 and 4 should be switched around (as 4 is meant to follow directly on from 2).
          Hide
          ggaskell Giles Gaskell added a comment - - edited

          Create a Pipeline Job in the Classic UI

          Just to clarify (as you've already indicated) that this is creating the Pipeline job or project itself through the classic UI, since creating the Pipeline through the classic UI implies this, which means the Jenkinsfile itself is not stored in source control.

          Show
          ggaskell Giles Gaskell added a comment - - edited Create a Pipeline Job in the Classic UI Just to clarify (as you've already indicated) that this is creating the Pipeline job or project itself through the classic UI, since creating the Pipeline through the classic UI implies this , which means the Jenkinsfile itself is not stored in source control.

            People

            • Assignee:
              dduportal Damien Duportal
              Reporter:
              dduportal Damien Duportal
            • Votes:
              0 Vote for this issue
              Watchers:
              2 Start watching this issue

              Dates

              • Created:
                Updated: