OpenDevStack Setup

This document will guide you through installing / maintaining an OpenDevStack installation.

From now on we assume, you work from a Bash (Cygwin / Linux).

Server prerequisites

In order to run the Atlassian suite and OpenShift, your host must have:

At least 16GB RAM and 32GB of available disk space
vm.max_map_count=262144 to run SonarQube (which can be set via sudo sysctl -w vm.max_map_count=262144)
A recent git version (>= 2.13.2)
A recent jq version (>= 1.5, see https://stedolan.github.io/jq/)

Local Setup

Before you can install OpenDevStack (no matter whether locally or on another server) you need to have the sources available on your local machine.

Repositories

If you do not have the ODS repositories setup yet, you can run repos.sh file. Before you run this script, keep in mind to have Git (>=2.13). Once you have that, you can then go to your Terminal and run:

mkdir -p opendevstack
cd opendevstack
curl -LO https://raw.githubusercontent.com/opendevstack/ods-core/master/ods-setup/repos.sh
chmod +x repos.sh

If you are installing OpenDevStack for the first time, run:

./repos.sh --init

If there is already an existing installation of OpenDevStack, run the following with a user that has write permission:

./repos.sh

The script will prompt you which Git ref you want to use. Select either master for bleeding edge or a more stable "version" such as 2.x. Afterwards running this script, all required repositories should be available locally.

Configuration

Go to ods-core and run:

make prepare-config

If 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

Tailor

We use Tailor to handle OpenShift templates and keep OpenDevStack resources in sync. Please see its installation instructions for your platform. The following lists 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

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

Infrastructure

Atlassian Tools

At this stage you can setup the Atlassian tools if they do not exist yet, or modify them as needed.

Documentation for this is missing.

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.

OpenShift cluster

At this stage you can setup the OpenShift cluster if it does not exist yet.

Documentation for this is missing.

If you are on Linux, oc cluster up will do the trick.

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-repos

Then, update them with the latest state so that they can be used e.g. from BuildConfig resources in OpenShift:

make sync-repos

You 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 master

OpenDevStack environment in OpenShift

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.

First, log into OpenShift with a user that has cluster-admin rights. In ods-core run:

make install-ods-project

Nexus

A central Nexus deployment is used to proxy packages and to store artifacts.

In ods-core run:

make install-nexus

Afterwards, run the initial configuration:

make configure-nexus

In 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-sonarqube

This 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-jenkins

Then, there are further Jenkins agent images for each quickstarter technology.

To create those images, run the following from ods-quickstarters:

make install-jenkins-agent

Document Generation service

At this stage you can setup or modify the image stream for the Document Generation service.

In ods-core run:

make install-doc-gen

Provisioning Application

At this stage you can setup or modify the provisioning application.

In ods-core run:

make install-provisioning-app

Congratulations! At this point you should have a complete ODS installation. Try it out by provisioning a new project with the provisioning application.