OpenDevStack Setup
This document will guide you through installing / maintaining an OpenDevStack installation.
Server prerequisites
Installing OpenShift is out of scope for this guide. We assume you have an OpenShift 3.11 cluster running already. If so, ensure that the cluster nodes have vm.max_map_count set to at least 262144, otherwise you’ll not be able to install SonarQube later on. You may change this setting via sudo sysctl -w vm.max_map_count=262144.
If you do not have an OpenShift cluster yet, and just want to try things out, you may use oc cluster up to spin up a temporary cluster. Note that this will only work on Linux and we recommend to have at least 16GB RAM and 32GB of available disk space.
|
Local Setup
From now on we assume you work from a Bash terminal (Cygwin / Linux). In this terminal, you’ll ned a recent git version (>= 2.13.2) and a recent jq version (>= 1.5, see https://stedolan.github.io/jq/) in your $PATH.
|
Repositories
Before you can install OpenDevStack (no matter whether locally or on another server) you need to have the ODS repositories available on your local machine.
For this purpose, ODS provides a script to setup all required repositories with the same Git ref easily.
This script needs to be downloaded to the umbrella directory which should hold all ODS respositories.
The following example shows how to do this for the master version, please use the exact version you want to install (e.g. v4.0.0):
UMBRELLA_DIR=~/opendevstack
GIT_REF=master
mkdir -p $UMBRELLA_DIR && cd $UMBRELLA_DIR
curl -LO https://raw.githubusercontent.com/opendevstack/ods-core/$GIT_REF/scripts/repos.sh
chmod +x repos.sh
./repos.sh --git-ref $GIT_REFAfter running this script, all required repositories should be available locally.
Configuration
Go to ods-core and run:
make prepare-configIf you want to install OpenDevStack for the first time, leave the BitBucket URL empty.
After the configuration is prepared (which means that a directory ods-configuration will be created if it does not exist yet),
fill out all the parameters in ods-core.env in directory ods-configuration for your installation.
Add all files of directory ods-configuration to git and commit the result. You don’t need to push yet, this will be done later.
"Preparing" also updates the sample files and checks if any params are present in the sample files but missing from the real file.
If you are using windows Cygwin or WSL remember to change ending line CRLF to LF before commit ods-core.env, you can find more information on configure Git ending line
|
Atlassian Suite
At this stage you have to setup the Atlassian suite (Jira, Confluence, Bitbucket, Crowd) if it does not exist yet. If you already have an installation the Atlassian suite, you now need to configure it to work with OpenDevStack.
| Documentation for the installation and configuration of the Atlassian suite is missing at the moment. The general setup is described in https://github.com/opendevstack/ods-core/tree/master/infrastructure-setup, but this will likely need adaption to your specific environment. |
After Crowd is running, ensure that there is a user corresponding to the CD_USER_ID_B64/CD_USER_PWD_B64 parameters in ods-core.env.
Bitbucket Repositories
On Bitbucket, there must be an OPENDEVSTACK project filled with the necessary repositories such as ods-core. To set them up, use:
make prepare-bitbucket-reposNotice that prepare-bitbucket-repos expects a running Atlassian suite (it will not spin up a new Bitbucket instance).
Then, update them with the latest state so that they can be used e.g. from BuildConfig resources in OpenShift:
make push-local-reposYou also need to update ods-configuration, which can be done via:
git remote add origin <bitbucket-ods-configuration-git-repo-url>
git push -u origin masterFinally, it is required to create a Git ref in the ods-jenkins-shared-library which matches the ODS version you want your users to consume (as specified by ODS_IMAGE_TAG in the configuration):
make set-shared-library-refOpenDevStack environment in OpenShift
Tailor
We use Tailor to handle OpenShift templates and keep OpenDevStack resources in sync. Tailor is a tool which needs to be installed on your local machine. Please see its installation instructions for your platform. Following are the version requirements:
| OpenDevStack version | Tailor version |
|---|---|
3.x |
>= 1.2.2 |
2.x |
>= 0.13.1 |
1.2.x |
= 0.9.3 |
1.1.x |
= 0.9.3 |
1.0.x |
= 0.9.1 |
0.1.x |
= 0.8 |
Central ODS project
OpenDevStack needs one central project in OpenShift, which will hold all shared resources such as images or deployments. This project is typically called ods, but you can customize this in the configuration via ODS_NAMESPACE.
For the following steps, you must be logged into OpenShift (using oc login <host> --token=<token>) with a user that has cluster-admin rights.
|
In ods-core run:
make install-ods-projectNexus
A central Nexus deployment is used to proxy packages and to store artifacts.
In ods-core run:
make install-nexusAfterwards, run the initial configuration:
make configure-nexusIn the course of this you will be prompted to set a new admin password.
The configure-nexus target is not idempotent yet, so it cannot be used for upgrading!
|
SonarQube
A central SonarQube deployment is used to analyze source code.
In ods-core run:
make install-sonarqubeThis will launch an instance of SonarQube.
The script will prompt for a new admin password. Once this has been set, an auth token for the Jenkins pipelines will be generated.
Both values are automatically written into ods-configuration/ods-core.env, which you then need to commit and push.
Also, you have to add the cd-user as a user in the project permissions of your Bitbucket OpenDevStack project. Read permission is sufficient.
Jenkins
Central Jenkins images (master, agent, webhook proxy) are used by every ODS project.
In ods-core run:
make install-jenkinsThen, there are further Jenkins agent images for each quickstarter technology.
To create those images, run the following from ods-quickstarters:
make install-jenkins-agent