Installing Jenkins page - Docker section seems uncomplete, no easy first test setup

[Zocker1999NET]

Problem with the Installing Jenkins page, source file

The Docker setup section seems incomplete to me. Today was my first try out Jenkins but it was not working flawless. The Docker setup mentions that I should run a container called "jenkins-docker" to allow dind actions (I know that these may not be safe in production, like it is explained in #3315, but to try out Jenkins this could be the fastest setup possible today). However after configuring Jenkins like expected in the manual, I discovered that Jenkins had no access to the said docker / dind agent (Jenkins was greeting me after the setup wizard with the hint I need to configure a node or cloud to run jobs.). So I concluded that I still need to configure this on my own, which is acceptable, however I did not know how to do that because the manual page does not explain this. I also did not found any other manual page explaining how to configure this special setup to be working.

I tried to configure it myself and installed the Docker Cloud plugin and tried to configure the connection to the dind client. It worked well until I tried the connection where it says that the "HTTP client tried to connect to a HTTPS server". From reading further material about the dind image, I learned that connecting to it in its default configuration does not only require TLS but also using a client certificate and that this certificate is stored and shared using the jenkins-docker-cert volume this manual expects you to create, which I did. However it was not possible for me to let Jenkins use this certificate without copying it to my machine and reuploading it to Jenkins using the Web UI.

I really like the idea of Jenkins being a fully open CI/CD platform and I really would like to use it before considering GitLab (because it is not fully open source). However this first experience was not great because I was expected to try things out on my own which I would expect should be at least mentioned in the manual.

Possible Solution

Describe in this page or another and link to it how to connect this dind container to Jenkins step-by-step. You can state that this setup is very insecure due to different reasons and should not be used in production, but providing such setup leaded me into trying out Jenkins just for a few minutes because it seemed easy.

Also may extend the manual to contain a step-by-step, complete process on how to install and use Jenkins on any machine capable of running Docker containers. This process should include configuring a single node or (even better) configuring Docker as cloud provider and, most important, include setting up a first pipeline for an example repository. This manual should only expect that the user is a capable Linux system administrator but should not require knowledge about Docker or Jenkins. You may link to external manuals or other pages of this manual where certain steps / processes / concepts are explained in more detail but not expect the user to read them first. This enables nearly any admin to try out Jenkins in a short time and see if it is a great tool for their use case or not. The manual page should cover common errors and also encourage users to submit their errors here so this manual page can improve over time. For my use cases, I think Jenkins is perfect but today I was not able to try it out so I could not evaluate that correctly.

[MarkEWaite]

Thanks for a great issue report @Zocker1999NET . Much appreciated!

The "Installing Jenkins" page does not describe agent configuration for any of the other platforms (war, macOS, Debian, Fedora, Red Hat, Windows, FreeBSD, etc.). I'm not strongly opposed to adding agent configuration information to that page, but considering the number of different agent configurations that are available, it seems the page will become quite unwieldy.

Would it be sufficient if the "Installing Jenkins" section on Docker included links to the Docker-specific tutorials like:

• Create a pipeline in Blue Ocean
• Build a Java app with Maven
• Build a Node.js and React app with npm
• Build a Python app with PyInstaller

Each of those tutorials uses a Docker image and runs a Docker agent on the user's computer (Windows, Linux, or macOS).

Would a link to one or more of those tutorials have significantly improved your initial experience?

[Zocker1999NET]

Thank you for answering so fast.

Create a pipeline in Blue Ocean seems to be the kind of manual I was searching for. It seems to be good guide on how to try out Jenkins.

However, I do not find how to configure an agent / connecting Jenkins to the dind container in the tutorials you linked. Am I just blind or is this missing there too? The missing guidance through the configuration of the agent is what disimproved my initial experience, the guidance on using Docker to install Jenkins itself and then enabling it was very good.

Even if (or because) there are a lot of configuration options (which is the reason why my first experience with Jenkins was not great), it would be a great help if you provide a page about how to configure an example agent (for example an dind container). If I manage to this successfully, then I am ready to try other configurations as well.

I compare this a little bit with GitLab CI because I have worked with GitLab before, but now wish to work with Jenkins because its fully open source, has more features and so can be more adapted to special workflows or setups. In GitLab CI, configuring a runner is very easy, you start the docker container required with certain arguments, run another command, insert the URL and a passphrase from your instance and voila, its working. I know that I cannot expect Jenkins to have a similar experience while supporting more complex configurations. But it would be great if there is a tutorial or guide which explains me how to build a similar setup without me expecting to know anything about Jenkins.

[MarkEWaite]

Each of the tutorials that I referenced uses the docker step to invoke a Docker image.

• Maven tutorial uses image 'maven:3-alpine'
• Node.js tutorial uses image 'node:6-alpine'
• Python tutorial uses image 'python:2-alpine'

Those tutorials allow the user to define the Docker image that should be used to run the build. If a user needs a different Docker image with different tools, they use the Docker image they choose.

[Zocker1999NET]

Sorry, I did not meant the image that will e.g. test or build the package. I was talking about the agent (for Jenkins a simple docker:dind container seems sufficient) that will invoke the containers for the pipeline executions. I think you call them nodes.

However when I follow the first tutorial you linked to, it just works which is great. But this is also confusing due to the fact that I have not registered an agent/node by myself. From the admin/user perspective, it looks like the shared jenkins-docker-certs volume is used to identify and connect to the agent/node. Otherwise I have no good reason why a master node appeared in the nodes page:

But I cannot remove it which is want I want (see setup description below).

Also the fact that there are two different UIs (blue ocean and default?) which show the same pipeline but seem to work completely is very confusing in my eyes.

What I was expecting from the tutorial to do was to register an agent/node before any pipeline execution would work. Because if this would be a part of the tutorial, it think it would be easy to setup Jenkins the way I want.

4 clicks away from the tutorial you sent, I think I found the guide for configuring additional nodes on other servers I was searching for, but it showed me that the architecture of Jenkins is much more complex than the architecture of GitLab. This guide finally introduces the master/agent concept I was expecting to read about in the beginners tutorial but then explains that horizontal growth means adding more masters? I understand that it can make sense in some contexts (for example bigger team environments) to let each team use its own instance to separate them, but horizontal growth means to me "running more jobs in parallel on different hardware" not "setting up more masters where each one requires its own custom configuration".

A small look on the setup I want to build: I have 3 servers for personal and family/friends projects, 1 main and 2 slaves. The main server is a fast machine, it does serve all websites and manages everything, so this one should run Jenkins but do not run any builds to prevent slowing down the other services. In addition, the two slaves are slow servers but do not anything else than waiting for a job to do. I want those to run all Jenkins builds. For the builds, the slaves should use Docker containers.
I did not find any tutorial so far which does me explaining how that may be possible. I think, it is, but in that time until such setup with Jenkins is working, I sadly will have transferred all my Git projects to a new GitLab instance and setup their CI to do what I want.

I would really like to use Jenkins but I think this would require too much work to do. My issue with Jenkins, as I see it now, is that the architecture is too complex to understand for newbies in a short time span and there is missing a front page clarifying e.g. that without further configuration, Jenkins is written to run builds on the same machine as the master is running on. This maybe seem naturally to users of Jenkins, but not to me.

@MarkEWaite, thank you for answering and trying to help me so far. If you want, you can send me further links to tutorials which may answering my questions. But I think Jenkins is not the solution I require, maybe due to its complexity or due to its original purpose.