diff --git a/README.md b/README.md index 5c51ad6..63cec30 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,8 @@ # Janus > A Dockerized Jenkins CI-CD system for Apella -Janus is a Docker image that contains an instance of Jenkins with all the necessary configuration built into it for handling the CI-CD of Apella. +Janus is a Docker image that contains an instance of Jenkins with all the necessary configuration built into it for +handling the CI-CD of Apella. ## Prerequisites @@ -9,7 +10,9 @@ Only needs a working installation of Docker. ## Installation -The credentials of the default admin user created are passed to Jenkins using docker secrets. The files containing the username and password to be used can be found at the paths `./jenkins/secrets/user` and `./jenkins/secrets/pass` respectively. Edit the files to change the default username and password. +The credentials of the default admin user created are passed to Jenkins using docker secrets. The files containing the +username and password to be used can be found at the paths `./jenkins/secrets/user` and `./jenkins/secrets/pass` +respectively. Edit the files to change the default username and password. Then run: @@ -26,9 +29,15 @@ make print-ssh-key Then, on Gitlab, add the public key to the deploy keys of the project. -Jenkins also needs an access token from Gitlab to update build statuses. Create an access token and add it to Jenkins under Global Credentials. +Jenkins also needs an access token from Gitlab to update build statuses. Create an access token and add it to Jenkins +under Global Credentials. -Lastly a Webhook must be added to Gitlab, pointing to the Jenkins project. On Gitlab, navigate to the Webhooks menu in the Settings of the project and add a new webhook pointing to `https://jenkins.apella.tk/project/staging-apella-multibranch-pipeline`. +Lastly a Webhook must be added to Gitlab, pointing to the Jenkins project. On Gitlab, navigate to the Webhooks menu in +the Settings of the project and add a new webhook pointing to +`https://jenkins.apella.tk/project/staging-apella-multibranch-pipeline`. + +In the `SETUP` you can find more details about the setup process, the credentials, plugins and other configuration that +is done automatically and how to change these. ## Contact diff --git a/SETUP.md b/SETUP.md index a8732eb..06b0af4 100644 --- a/SETUP.md +++ b/SETUP.md @@ -4,49 +4,52 @@ Welcome to **Janus** installation guide (the Jenkins based CI-CD systyem for Ape **This installation guide is intended for computers using Debian based, Linux distributions!** -The software provided will work on other operating systems too, after loosely following this guide, but changes and decisions may have to be made along the way. +The software provided will work on other operating systems too, after loosely following this guide, but changes and +decisions may have to be made along the way. Although the guide is pretty detailed don't hesitate to open an issue or contact us directly for any questions. ## Introduction -Janus is a docker image based on the official Jenkins image. Its purpose is to be used as a CI-CD system for Apella, but can be easily modified for use with any project, especially decentralized apps using the truffle suite. +Janus is a docker image based on the official Jenkins image. Its purpose is to be used as a CI-CD system for Apella, +but can be easily modified for use with any project, especially decentralized apps using the truffle suite. ## Prerequisites -To execute the commands bellow you should have a working docker installation on the machine you intend to use. If you don't have that we encourage you to use the installation script `install.sh` in the root directory. +To execute the commands bellow you should have a working docker installation on the machine you intend to use. The only other prerequisite is that ports 80 and 443 should be free. ## Building the image To build the image use the makefile provided: -```bash +```sh make build ``` ## Installation -Set a variable to hold the host's docker version: -```bash -HOST_DOCKER_VERSION=$(docker version --format '{{.Server.Version}}') -``` - You are now ready to start the Jenkins container: -```bash +```sh make run ``` ### Admin username and password -An admin user is automatically created. The username and password of this user are defined in the files `jenkins/pass` and `jenkins/user` respectively. **If you change them you need to build the image again for the changes to take effect.** +An admin user is automatically created. The username and password of this user are defined in the files +`jenkins/secrets/adminUsername` and `jenkins/secrets/adminPassword` respectively. +**If you change them you need to build the image again for the changes to take effect.** ### Jenkins configuration -The initial configuration done includes setting up the security, setting up the system url and adding an SSH keypair credential to the system. The groovy scripts that make this happen can be found in the directory `jenkins/configuration` +The initial configuration done includes setting up the security, setting up the system url, adding an SSH keypair +credential to the system and finally adding a username and password credential for accessing docker hub. The groovy +scripts that make this happen can be found in the directory +`jenkins/configuration`. -The SSH keypair that is added is created on build time. You can get the public key running the utility script that was written for convenience: -```bash +The SSH keypair that is added is created on build time. You can get the public key running the utility script that was +written for convenience: +```sh ./utility-scripts/printJenkinsGitlabSSHPublicKey.sh ``` @@ -54,32 +57,29 @@ The SSH keypair that is added is created on build time. You can get the public k ### Plugins installed -A number of plugins are automatically installed. A list of these plugins can be found in the file `jenkins/plugins.txt`. To update the plugins after having used the container and made changes, you may run the utility script that was written for convenience: -```bash +A number of plugins are automatically installed. A list of these plugins can be found in the file `jenkins/plugins.txt`. +To update the plugins after having used the container and made changes, you may run the utility script that was written +for convenience: +```sh ./utility-scripts/updateJenkinsPlugins.sh ``` **You will need to build the image again for the changes to take effect.** -### NodeJs versions installed - -The plugins installed include the NodeJs plugin. A default configuration for the plugin is also provided in the file `jenkins/groovy/nodejs.groovy`. The script adds two configurations of the plugin, using node versions 12 and 13. Both configurations include the global installation of eslint and truffle npm packages. - -**If you change the configuration script you need to build the image again for the changes to take effect.** - ### Jobs added -A number of jobs (specific to Apella) are automaticaly configured. The config XML files are located in the directory `jenkins/jobs`. +A number of jobs (specific to Apella) are automatically configured. The config XML files are located in the directory +`jenkins/jobs`. ## Uninstalling To uninstall Janus just stop the container and remove the image: -```bash +```sh make clean-data clean-images ``` You may also need to remove the files stored in the volumes: -```bash +```sh sudo rm -rf volumes/ ```