We aim to make it as simple as possible for users to try out Syndesis. If you want to try out locally on your laptop, follow the Using Minishift instructions.

Using Minishift

Minishift is a tool that helps you run OpenShift locally by running a single-node OpenShift cluster inside a VM locally. With Minishift you can easily try out Syndesis without requiring a “real” cluster or servers, a laptop will suffice.


Minishift itself

You’re going to need a working Minishift installation, which is really easy. If you haven’t got Minishift already installed, please follow the Minishift installation documentation.

Fire up Minishift if it’s not already running. You need to add some memory, 4192 or more is recommended, and allocate a couple of CPUs:

$ minishift start --memory 4192 --cpus 2

Tip: If you want to switch the OpenShift config permanently use:

$ minishift config set memory 4192
$ minishift config set cpus 2

GitHub registered application

You also need a GitHub application registered at https://github.com/settings/developers. While registering, you’ll need to provide a callback URL. The callback URL will be the output of:

$ echo https://syndesis.$(minishift ip).xip.io

Once you have registered the application, you will get a <GITHUB_CLIENT_ID> and a <GITHUB_CLIENT_SECRET>. These should be used in the commands below.

Template selection

Deploying Syndesis is made easy thanks to OpenShift templates.The template to use in the installation instructions depend on your use case:

  • Developer : Use the template syndesis-dev-restricted which directly references Docker images without image streams. Then when before building you images e.g. with mvn fabric8:build set your DOCKER_HOST envvar to use the Minishift Docker daemon via eval $(minishift docker-env). After you have created a new image you simply only need to kill the appropriate pod so that the new pod spinning up will use the freshly created image.

  • Tester / User : In case you only want to have the latest version of Syndesis on your local Minishift installation, use the template syndesis-restricted which uses image stream referring to the published Docker Hub images. Minishift will update its images and trigger a redeployment when the images at Docker Hub changes. Therefor it checks every 15 minutes for a changed image. You do not have to do anything to get your application updated, except for waiting on Minishift to pick up new images.

Depending on your role please use the appropriate template in the instructions below.

Deployment instructions

Set your GitHub credentials from your registered app in your shell:

$ export GITHUB_CLIENT_ID=...

Install the OpenShift template (syndesis-dev-restricted.yml or syndesis-restricted.yml as discussed above):

$ oc create -f https://raw.githubusercontent.com/syndesisio/syndesis-openshift-templates/master/syndesis-dev-restricted.yml

In order to make it easy to run Syndesis on a cluster without requiring admin rights, Syndesis takes advantage of OpenShift’s ability to use a Service Account as an OAuth client. Before we create the app, we’ll need to create this Service Account:

$ oc create -f https://raw.githubusercontent.com/syndesisio/syndesis-openshift-templates/master/support/serviceaccount-as-oauthclient-restricted.yml

Deploy syndesis using the following command, replacing “syndesis-dev-restricted” with “syndesis-restricted” depending on the template you have just installed:

$ oc new-app syndesis-dev-restricted \
    -p ROUTE_HOSTNAME=syndesis.$(minishift ip).xip.io \
    -p OPENSHIFT_MASTER=$(oc whoami --show-server) \
    -p OPENSHIFT_PROJECT=$(oc project -q) \
    -p OPENSHIFT_OAUTH_CLIENT_SECRET=$(oc sa get-token syndesis-oauth-client) \

Wait until all pods are running:

$ watch oc get pods

You should now be able to open https://syndesis.$(minishift ip).xip.io in your browser.