Installing Jenkins page - Change recommended Docker image to jenkins/jenkins

[scottashipp]

Problem with the Installing Jenkins page, source file

Under the section titled Downloading and running Jenkins in Docker it says:

There are several Docker images of Jenkins available.

The recommended Docker image to use is the jenkinsci/blueocean image (from the Docker Hub repository). This image contains the current Long-Term Support (LTS) release of Jenkins (which is production-ready) bundled with all Blue Ocean plugins and features. This means that you do not need to install the Blue Ocean plugins separately.

This information conflicts with other documentation that says that jenkins/jenkins is the recommended Docker image.

I asked in the jenkinsci/docker gitter and Mark Waite confirmed that the recommended image is jenkins/jenkins so this documentation should be updated to reflect that.

Screenshots

N/A

Possible Solution

Update these paragraphs (and those following) to reflect jenkins/jenkins as the recommended Docker image.

Links

• https://issues.jenkins-ci.org/browse/WEBSITE-474 - old issue in Jenkins Jira

[MarkEWaite]

My reason to prefer the jenkins/jenkins image instead of the jenkins/blueocean image is that the jenkins/jenkins image avoids the controversy of allowing Docker inside the Docker container.

There has been community discussion in the past trying to find the right balance between ease of adoption and Docker preferred practices. We'll likely need to revisit that discussion to assure we're aligned on the need for the blueocean image and the recommendation to prefer jenkins/jenkins image.

[oleg-nenashev]

It is not only about preferring the image, BlueOcean one is severely flawed when it comes to the installation wizard. Speaking of the issue itself, there was an attempt to fix it by @alecharp in #2148 , but it has not been finalized.

We need a complete rewrite of the guide, and this topic is suggested for the UI/UX hackfest next week: https://www.jenkins.io/events/online-hackfest/2020-uiux/#user-documentation. @scottashipp would you be interested to join the team and help with rewriting the guide?

[vsilverman]

Results of rewriting Installing Jenkins page also should not conflict with results of rewriting Jenkins and Docker page.

[scottashipp]

@oleg-nenashev I would normally be very interested but unfortunately I am in crunch time for the foreseeable future.

[oleg-nenashev]

@scottashipp No worries! We plan to get this issue fixed anyway, hopefully it will happen soon

[getJv]

Hello guys. I've followed the guide and didn'd find the ambiguos docker-image recommendation. is it already fixed? if not and someone else it is workink on it, how can i help with it?

[MarkEWaite]

Hello guys. I've followed the guide and didn't find the ambiguous docker-image recommendation. is it already fixed? if not and someone else it is working on it, how can i help with it?

@getJv the recommendation is not ambiguous as much as it is wrong for a production Jenkins instance and it would be best if we could find a way to not require the blue-ocean image for tutorials. The installing guide and four of the tutorials (Maven, NodeJS, Python, and LabView) use the blue-ocean image.

The tutorials need the blue-ocean image (for now) because they need to run Docker agents and the tutorial is already running as a Docker image. Running a docker image inside another docker image requires some choices that the Docker community does not recommend for production instances.

The discussion of the issues with the choice of blue-ocean as the image are in #2148 . This ticket, #2148, and #3328 .

[getJv]

I get it. When i read the description at first time i guess understand the documentation was saying that both images were the recommended choices (ambiguous). But after read the related issues the you pointed, looks like we have a new image (jenkins // jenkis).

I read the image descripion and it looks like quite good to me. So in order to do the issue, what we need to do? rewrite the documentations samples using the new image? or something else? or just keeping waiting? :)

[MarkEWaite]

I read the image descripion and it looks like quite good to me. So in order to do the issue, what we need to do? rewrite the documentations samples using the new image? or something else? or just keeping waiting? :)

The biggest challenge that I see is the technical hurdle of trying to provide an agent execution environment from the master. The current setup is described in the "Installing" section on Docker and is used in the tutorials.

The other installation descriptions do not describe how to connect agents, but the Docker install does. The Docker installation instructions describe how to use the "Docker in Docker" image.

We could stop describing agent connection processes in the Docker install or we could find a way to make the jenkinsci/jenkins Docker image allow agents so that it could replace the jenkinsci/blueocean image. Either choice would be valid for the "Installing Jenkins" page

The tutorials are more difficult. The Docker in Docker agent technique is used in the tutorials to provide an agent with the specific tools for that tutorial. Each tutorial needs a different set of build tools (Python and Pyinstaller for the Python tutorial, Java and Maven for the Maven tutorial, NodeJS and npm for the Node tutorial). The Docker in Docker technique allows those tools to be selected easily. The ease of using those tools is part of what makes the tutorials compelling. However, we may need to increase the complexity of the tutorials by teaching the tutorial student how to connect a Jenkins agent in Docker to a Jenkins server in Docker without the convenience of Docker in Docker.

@oleg-nenashev or @alecharp may have better suggestions to offer.

[nikstur]

There has been community discussion in the past trying to find the right balance between ease of adoption and Docker preferred practices.

When you refer to the Docker preferred practices @MarkEWaite, you refer to mounting the Docker socket instead of using DinD, correct? I think this is the article most people stumble upon when reading about this issue.

I think the problem can be solved by providing a docker-compose file using the jenkins/jenkins image with the docker socket mounted inside. This would get people started quickly., without setting up networks and volumes manually. It would surely violate the best practice of running no executors on the master, but I guess this can be sacrificed for simplicity's sake.

Overall, I believe, this would decrease complexity and be much more extensible as a user would simply have to add an agent and disable the executors on the master to get an almost production-ready setup.

Example docker-compose.yaml

version: '3'
services:
  jenkins-master:
    build: ./jenkins-master/Dockerfile
    volumes:
      - jenkins-data:/var/jenkins_home
      - /var/run/docker.sock:/var/run/docker.sock
    ports:
      - 8080:8080
volumes:
  jenkins-data:

Example Dockerfile at ./jenkins-master/Dockerfile

FROM jenkins/jenkins:latest
USER root
RUN curl -fsSL https://get.docker.com | sh

The only thing for a production setup missing here is to change the docker group inside the container to the same GID as on the host and adding the jenkins user to it to avoid running jenkins as root. This is, however, not very straighforward because the user needs to find out the GID of the docker groups himself. Also some users possibly have not even added their user to the docker group and instead use sudo to interact with docker.

Additions to the Dockerfile to not run as root:

RUN groupmod -g <GID of docker group on the host> docker
RUN usermod -aG docker jenkins
USER jenkins

This could be added to the installation instructions when it is deemed to be too insecure to run jenkins as root (which it is).

In short, this would make adoption easier (or at least as easy as it is) and follow the Docker best-practices. I don't see why this same setup couldn't be used in the tutorials as well.

[vsilverman]

I think this is the article most people stumble upon when reading about this issue.
Solution to the issue is provided by the author of initial DinD:

1. adding -v /var/run/docker.sock:/var/run/docker.sock \ to docker run
2. installing the Docker CLI

Installation part may be achieved e.g. by

• building a (demo or tutorial) image derived from Jenkins "official" LTS version
• including in Dockerfile snippet like this:

Still there are issues around above and related solutions (including running privileged docker), discussion of which is summarized here.
One possible way to avoid misunderstanding - add a warning to the docs and ask to use with caution in production.

[vsilverman]

@MarkEWaite , @oleg-nenashev, I would be glad to work on this issue

[vsilverman]

Applying proposed changes to the demo config-as-code image , created by @oleg-nenashev , works. There are IMO several tasks, resulting from this work:

• simplifying customized docker image to facilitate adoption by new customers/contributors
• implementing tutorial demos, based on customized docker image
• updating https://jenkins.io/ pages with docker-related documentation, referencing implemented solutions and tutorials .

As always any comments on best approaches for moving forward are welcome.

[MarkEWaite]

The Docker installation instructions no longer suggest the blueocean image. In that sense, this issue is resolved as initially reported.