Hop is a CLI tool written in python you can use to manage GoCD installations using docker and pipeline-as-code.
The fastest way to try hop
is to use the hop-builds-hop
example. To try it, clone this very repository, install hop and provision the example.
Hop has the following dependencies:
python3.5
pip3
htpasswd
docker
Install hop with:
$ pip3 install git+https://github.com/dudadornelles/hop.git
Then, to provision and configure hop-builds-hop
, do:
$ git clone https://github.com/dudadornelles/hop.git
$ cd hop/examples/hop-builds-hop/
$ hop provision
$ hop configure apps/ --password admin
Open your browser on https://localhost:18154
and login as admin:admin
. In no time you'll see the hop
pipeline running.
Welcome to hop. Hop was created to speed up the process of provisioning, managing and configuring GoCD through code.
Hop has three main concepts:
- Providers: a provider manages the lifecycle of the GoCD server and agents. It is a plugin system, so you can decide what to use as
the underlying infrastructure by chosing/implementing a provider. Currently
hop
ships with alocal_docker
provider, that uses a local docker socket to spin up the server and agents in your local docker daemon. - Plans: plans are an abstraction one-level higher then GoCD's pipelines. A plan is a collection of 1 or more pipelines. Plans are also a plugin system and are written in python using the gomatic library.
- Apps: apps or 'app definitions' are data structures with a 'plan', that get processed and transformed into pipelines.
Hop is specially valuable for platforms where there are 'categories' of applications (that get built/deployed in similar ways), for now you can define a 'plan' to represent a 'category' and thus streamline the process of creating and (most important) deploying new applications.
python3.5
pip3
htpasswd
docker
Install with hop and python3 and pip3:
$ pip3 install git+https://github.com/dudadornelles/hop.git
Initialize hop
in a destination directory:
$ hop init myGoCD
Running hop init
will place ask your for a password. Remember this passwrod as it is the GoCD admin password. When hop init
is done,
cd into your hop
root and you will find two files:
- hop.yml: the main configuration file for hop.
- passwd: the htpasswd password file.
Run hop provision
from the root folder to invoke the provider and start the GoCD server and agents.
$ cd myGoCD
$ hop provision
hop:: Provisioning GoCD
hop:: Using local_docker provider
hop:: Verifying presense of images
hop:: Starting GoCD server from gocdhop/myGoCD-server
hop:: GoCD not yet initialized at https://localhost:18154. Will try again in 15 secs
hop:: GoCD not yet initialized at https://localhost:18154. Will try again in 15 secs
hop:: GoCD is up and running
hop:: Updating passwd
hop:: Adding security config to cruise-config.xml
hop:: Starting myGoCD-agent-0 from gocdhop/hop-agent
hop:: Starting myGoCD-agent-1 from gocdhop/hop-agent
hop:: GoCD is up and running
hop:: GoCD is up and running on https://localhost:18154
To configure hop, create a folder for your apps (we call this a 'context'):
$ mkdir apps
Add a app definition in a yaml file inside that context.
# apps/hop.yml
hop:
plan: config_repo
git_url: https://github.com/dudadornelles/hop.git
Run hop configure <context>
$ hop configure apps/
hop:: executing 'config_repo' plan for hop
You'll find the available commands by running
$ hop -h
usage: hop [-h] {init,provision,configure,destroy} ...
positional arguments:
{init,provision,configure,destroy}
init initializes hop
provision provisions GoCD
configure configures GoCD
destroy destroys GoCD
optional arguments:
-h, --help show this help message and exit
Initializes hop in dest_dir
.
$ hop init -h
usage: hop init [-h] [--skip-passwd] dest_dir
positional arguments:
dest_dir destination directory for hop
optional arguments:
-h, --help show this help message and exit
--skip-passwd skip creating passwd file during init
Runs the provision
method of the provider
. The provider is specified in the hop.yml
file. Eg:
# hop.yml
provider:
name: local_docker
$ hop provision -h
usage: hop provision [-h]
optional arguments:
-h, --help show this help message and exit
Looks for apps in context
and executes them using the declared plan
. Example:
# apps/hop.yaml
hop:
plan: config_repo
git_url: https://github.com/dudadornelles/hop
Then running hop configure apps/
will add the git_url
as a yaml config repo in GoCD.
$ hop configure -h
usage: hop configure [-h] [-H HOST] [-u USER] [-p PASSWORD] context
positional arguments:
context A folder with a set of yml files for app definitions
optional arguments:
-h, --help show this help message and exit
-H HOST, --host HOST GoCD host. e.g: localhost:8153
-u USER, --user USER User with admin role
-p PASSWORD, --password PASSWORD
Password for user
Invokes the provider to destroy all resources that were created for this GoCD installation.
$ hop destroy -h
usage: hop destroy [-h] [-f]
optional arguments:
-h, --help show this help message and exit
-f, --force Don't ask for confirmation before destroying GoCD
Make sure you have docker running.
Hop is written in python 3.5, and we recommend you use virtualenv to develop hop. After cloning this repository, cd into hop
and run:
virtualenv -p python3.5 .venv && source .venv/bin/activate
make init
The current integration test suite runs against a local Docker provider. This means you need to have Docker installed and running. To run the tests:
make develop
make unit # unit tests
make integration # integration tests
make test # pylint, unit and integration tests
Take a look at the Makefile
to see what else is available.