Development QuickStart

If you’d like to get a local development environment up and running, for both the UI and REST API, this is how you’d do it.

Tips

Build on branch, not master.
Callback URL Example: https://syndesis.192.168.64.29.nip.io/api/v1/credentials/callback

Requirements

You can follow these steps if it’s your first time setting up Syndesis, or if you want a fresh local installation to replace an existing one. Some environment-specific instructions may be available below as well.

Make sure you have installed node version >= 6.x.x and Yarn version >= 0.18.1.
Get a developer deployment of Syndesis running in a Minishift environment as described in the Syndesis Quickstart. Most are specific to your environment, so follow the sections below for a quick setup. The general instructions are:
- Install a hypervisor for Minishift.
- Install Minishift.
- Install the OpenShift CLI.
- Make sure it’s in your $PATH

macOS

If you’ll be using the Homebrew method, you’ll obviously need to have Homebrew installed. Then, to install the hypervisor for Minishift and Minishift itself:

$ brew install docker-machine-driver-xhyve
$ brew cask install minishift

Finally, to install the OpenShift CLI, we recommend using Homebrew: brew install openshift-cli

Linux & Windows

Install a hypervisor for Minishift. For macOS, we recommend using the Docker xhyve plugin here, which can be installed using Homebrew.
Install Minishift. For macOS, we recommend you use the Homebrew method.

Please note that you need to have the oc binary available in your PATH. To do that, see here: https://docs.openshift.org/latest/cli_reference/get_started_cli.html

First-Time Setup

The goal here is to download the project to your laptop/PC, and to install Minishift, the VM that contains OpenShift.

$ git clone https://github.com/syndesisio/syndesis.git # or own fork
$ cd syndesis

# install minishift
$ syndesis minishift --full-reset --project syndesis --maven-mirror --disk-size 60GB

You can also include other options when setting up, for example including an addon:

# install syndesis with jaeger addon
$ syndesis minishift --install --project syndesis --nodev --app-options " --addons jaeger"

The jaeger is installed to support the activity log backed by jaeger opentracing, which is faster than the activity log stored in postgresql.

Running without Kubernetes/OpenShift

For some development tasks you can run Syndesis without running on a Kubernetes/OpenShift cluster. You won’t be able to publish integrations, see activities or gather metrics, or any other functionality that requires a running cluster. This is best suited for quick turnaround development of backend APIs together with UI features. You’ll need three components running: the Syndesis backend, the PostgreSQL database it uses and the UI.

Start by running a PostgreSQL database in a Docker container:

# Using Docker
$ docker run -d --rm -p 5432:5432 -e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=password -e POSTGRES_DB=syndesis postgres
# or Podman
$ podman run -d --rm -p 5432:5432 -e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=password -e POSTGRES_DB=syndesis postgres

the `--rm` option will remove the container once done and all the stored data in the database with it, if you wish to keep the data omit that option

Next run the Syndesis backend, this step requires that you have downloaded all the dependencies and built the backend:

$ syndesis build -f -c --backend # to download dependencies and build the backend
$ (cd app && ./mvnw -f server/runtime spring-boot:run)

The backend is started once you see a line containing this in the output:

Started Application in 28.9 seconds (JVM running for 29.615)

To connect the debugger using Java TM Debug Wire Protocol, connect to port 8888.

As an alternative you can run Syndesis from your Java IDE by launching io.syndesis.server.runtime.Application from the server-runtime Maven module and specifying additional Java system properties to disable subsystems that are not available outside of the OpenShift cluster:

-Dcontrollers.dblogging.enabled=false
-Dencrypt.key=supersecret
-Dfeatures.monitoring.enabled=false
-Dmeta.service=localhost:9090
-Dmetrics.kind=noop
-Dopenshift.enabled=false
-Dspring.cloud.kubernetes.enabled=false

You can optionally run the Metadata backend as well, this is needed for verifying connections and dynamic parameter support. You have already built the Metadata using syndesis build ... --backend, and you only need to start it by running:

$ (cd app && ./mvnw -f meta spring-boot:run)

To connect the debugger using Java TM Debug Wire Protocol, connect to port 9999.

As an alternative you can run Metadata backend from your Java IDE by launching io.syndesis.connector.meta.Application from the meta Maven module and specifying these additional Java system properties:

-Dserver.port=9090
-Dmanagement.server.port=9091
-DLOADER_HOME=target

To build the UI, run:

$ syndesis ui --install --build

After that UI can be started by running (in two separate terminal sessions):

$ (cd app/ui-react && yarn watch:packages)
$ (cd app/ui-react && BACKEND=http://localhost:8080 yarn watch:app:proxy)

You might find that the default memory settings of NodeJS are not sufficient enough to run the UI in debug mode. And to that end see error like:

FATAL ERROR: Ineffective mark-compacts near heap limit Allocation failed - JavaScript heap out of memory

To help with that set the NODE_OPTIONS environment variable for example:

$ export NODE_OPTIONS=--max-old-space-size=4096

Also, when starting the UI you might see a browser window pop up and close, this is expected. This functionality is in place to get the cookie when the UI is trying to access backend running behind OAuth proxy, in place of the OpenShift login screen.

You can now access a running instance at https://localhost:3000.

Use latest image instead of fixed version

Sometimes the operator pod does override the version we have installed so we can’t really test our own custom code. We can manually set the image stream to latest in OpenShift console and build the syndesis-operator image with syndesis CLI.

eval $(minishift docker-env)
oc login -u developer -p developer
oc project syndesis

syndesis build -t -f -m operator

docker login -u developer -p $(oc whoami -t) $(minishift openshift registry)

docker tag syndesis/syndesis-operator $(minishift openshift registry)/syndesis/syndesis-operator

docker push $(minishift openshift registry)/syndesis/syndesis-operator

After this we have a new syndesis-operator:latest image in the Minishift registry and the syndesis-operator deployment starts working. The operator will automatically setup arbitrary deployments for syndesis-oauthproxy, syndesis-db, syndesis-prometheus and pull the images.

Get the Latest Changes

Every now and then we should update the code we are working on to get the latest changes to make pull requests easy to merge.

$ git pull --rebase origin $branch

where $branch is usually master.

Install Maven Nexus as mirror

It is a good idea to have a local Nexus installation that Maven can use to cache dependencies. We can automatically install a maven mirror on our environment with the following command:

$ syndesis dev --install-maven-mirror

You should check now the Day to Day section