A quick, easy-to-setup Jenkins environment, intended to be run on the developer's local computer to monitor progress; i.e. view test results, code coverage, etc, is presented here.
The Jenkins setup is based on a primary controller Jenkins container named jenkins and a permanent worker agent named agent.
Make a .jenkins directory and a Release directory in your home directory path before proceeding:
mkdir ~/.jenkins
mkdir ~/Release
The .jenkins is where the Jenkins files can persists and the Release is where the released build packages will be copied.
Modify the symbolic link ci/jenkins/.project_repo to point to your project local repository root path, so that Jenkins can access the current uncommitted changes of your local repository. The default symbolic link just points to the default workspace project. Then to make sure Git ignores the changes you have made to .project_repo symbolic link:
git update-index --assume-unchanged .project_repo
Note that the ci/jenkins/.project_repo symbolic link is used throughout the various tool-chain scripts.
Generate the needed environment variables and SSH key pair for Jenkins agent communication by running the supplied script:
cd ci/jenkins/
../scripts/generate-keys-envs.sh
This will create a .env, .jenkins_agent and .jenkins_agent.pub files you will require in the following steps.
Now start up the Jenkins containers using Docker Compose:
docker compose up -d
Open your browser on your local host to http://localhost:8080.
You will see the initial Jenkins page presenting the Unlock Jenkins page; you will need to enter the hex code, which you can attain from the logs by running:
docker logs jenkins
Here is an example output with some hex code here marker:
*************************************************************
*************************************************************
*************************************************************
Jenkins initial setup is required. An admin user has been created and a
password generated.
Please use the following password to proceed to installation:
<some hex code here>
This may also be found at: /var/jenkins_home/secrets/initialAdminPassword
*************************************************************
*************************************************************
*************************************************************
You can also just check from your local ~/.jenkins path:
cat ~/.jenkins/secrets/initialAdminPassword
If needed you can login to the jenkins container as follows:
docker exec --interactive --tty --user jenkins \
--workdir /var/jenkins_home/ jenkins /bin/bash --login
Similarly to login to the agent containers:
docker exec --interactive --tty --user jenkins \
--workdir /home/jenkins agent /bin/bash --login
If needed you can also login as root to both of these containers; this could come handy when troubleshooting issues:
docker exec --interactive --tty --user root \
--workdir /root/ <container-name> /bin/bash --login
Where can be jenkins or agent.
On startup choose the option to install recommended plugins.
In addition to those, install plugins:
- Last Changes
- HTML Publisher
- Valgrind
Click on the Manage Jenkins menu on the side panel.
Then go to Credentials.
Click on the (global) text under Domains.
Global credentials (unrestricted) page will open, click Add Credentials.
Set these options on this screen.
-
Select SSH Username with private key
-
Scope as System (Jenkins and nodes only)
-
Pick an ID; e.g. jenkins
-
Add a description; e.g. "jenkins agent connection"
-
Enter jenkins for a username
Check the Private Key checkbox item and copy/paste the text from the .jenkins_agent private key.
Leave the Passphrase empty.
Click Create.
Again click on the Manage Jenkins, and select Nodes instead of credentials.
Click + New Node, pick Node name as jenkins-agent and check Permanent Agent and click Create.
Leave Number of executors as 1.
Set Remote root directory as /home/jenkins/agent.
For Usage select Use this node as much as possible.
For Launch method select Launch agents via SSH.
Enter localhost as Host and select the credentials we made in the previous section.
For the Host Key Verification Strategy, select Non verifying Verification Strategy.
Now click Advanced... to reveal more options.
For Port put 8022.
For JavaPath put /opt/java/openjdk/bin/java.
Set Connection Timeout in Seconds to 60, Maximum Number of Retries to 10, and Seconds To Wait Between Retries to 15.
Click Save.
In the Nodes page you should see the jenkins-agent statistics display valid values. If you see NA in these fields you may need click the node jenkins-agent then Log from the sidebar to diagnose the issue.
We intend this Jenkins setup to be a local and convenient setup that can test your local changes without you needing to commit them. For this reason we simply mount the symbolically linked path ci/jenkins/.project_repo, which must point to your local repository, to the Jenkins container /opt/project_repo path. The build process will make disposable copies internally to prevent modifications.
Configure a Pipeline named YOUR-PROJECT_NAME with Definition as Pipeline script from SCM and SCM type as Git, with the following settings:
- Repository URL: /opt/project_repo
- Credentials: empty
- Branches to build: */main
Then specify the Script Path as the path to your project Jenkinsfile within your project with respect to your project root path.
You should be able to click on YOUR-PROJECT-NAME from the Dashboard and then click Build Now to start the pipeline.
Jenkins can be restart by navigating your browser to http://localhost:8080/restart.
To delete all builds click Manage Jenkins and select Script Console, then type and run the following script:
def jobName = "YOUR-PROJECT-NAME"
def job = Jenkins.instance.getItem(jobName)
job.getBuilds().each { it.delete() }
job.nextBuildNumber = 1
job.save()
To run Jenkins plug-in HTML Publisher we have introduced a startup-properties.groovy file to init.groovy.d path of our Jenkins home that allows publishing HTML documents. In doing this we are declaring we trust the HTML documents we produce in our project.
Also this Jenkins install is intended to be a local installation only to aid in the development process rather than a wider server or cloud setup. If this Jenkins configuration is ever considered for wider usage please consider this topic.
Note security notification on this topic Configuring Content Security Policy. Risk must be assess per HTML publishing application.
Note Jenkins doesn't seem to allow connection when using the default ssh-keygen RSA key, you either have to specify for example '-b 4096' or just use the recommended ed25519, which is what we do.
If the agent connection isn't working here are some checks you can do.
Login to the Jenkins agent container and verify the authorized_keys have been installed by the environment variable JENKINS_AGENT_SSH_PUBKEY:
$ docker exec --interactive --tty --user jenkins \
--workdir /home/jenkins agent /bin/bash --login
jenkins@agent:~$ cat .ssh/authorized_keys
ssh-ed25519 *<.jenkins_agent.pub file contents>*
Login to the Jenkins controller jenkins container and verifty SSH to the agent using the private key .jenkins_agent works:
$ docker exec --interactive --tty --user root \
--workdir /root/ jenkins /bin/bash --login
root@jenkins:~# ssh -i ./ci/jenkins/.jenkins_agent jenkins@agent