Introduced in GitSwarm 2017.1.
This document will guide you through installing and configuring Koding with GitSwarm.
First of all, to be able to use Koding and GitSwarm together you will need public access to your server. This allows you to use single sign-on from GitSwarm to Koding and using vms from cloud providers like AWS. Koding has a registry for VMs, called Kontrol and it runs on the same server as Koding itself, VMs from cloud providers register themselves to Kontrol via the agent that we put into provisioned VMs. This agent is called Klient and it provides Koding to access and manage the target machine.
Kontrol and Klient are based on another technology called Kite, that we have written at Koding. Which is a microservice framework that allows you to develop microservices easily.
Minimum requirements are;
If you plan to use AWS to install Koding it is recommended that you use at least a c3.xlarge instance.
Koding can run on most of the UNIX based operating systems, since it's shipped as containerized with Docker support, it can work on any operating system that supports Docker.
Required services are:
which are also provided as a Docker container by Koding.
You can run docker-compose environment for developing koding by executing commands in the following snippet.
git clone https://github.com/koding/koding.git
cd koding
docker-compose -f docker-compose-init.yml run init
docker-compose upThis should start koding on localhost:8090.
By default there is no team exists in Koding DB. You'll need to create a team called gitlab which is the default team name for GitSwarm integration in the configuration. To make things in order it's recommended to create the gitlab team first thing after setting up Koding.
To install GitSwarm to your environment for development purposes it's recommended to use GitSwarm Development Kit which you can get it from here.
After all those steps, gitlab should be running on localhost:3000
Integration includes following components;
project_created, user_joined etc.)Run/Try on IDE (Koding) buttons on GitLab Projects, Issues, MRs)As it's pointed out before, you will need public access to this machine that you've installed Koding and GitSwarm on. Better to use a domain but a static IP is also fine.
For IP based installation you can use xip.io service which is free and provides DNS resolution to IP based requests like following;
As Koding needs subdomains for team names; foo.127.0.0.1.xip.io requests for a running koding instance on 127.0.0.1 server will be handled as foo team requests.
You need to enable Koding integration from Settings under Admin Area. To do that login with an Admin account and do followings;
Enable Koding checkboxprovide GitSwarm team page for running Koding instance as Koding URL*
For Koding URL you need to provide the gitlab integration enabled team on your Koding installation. Team called gitlab has integration on Koding out of the box, so if you didn't change anything your team on Koding should be gitlab.
So, if your Koding is running on http://1.2.3.4.xip.io:8090 your URL needs to be http://gitlab.1.2.3.4.xip.io:8090. You need to provide the same host with your Koding installation here.
We need Application ID and Secret to enable login to Koding via GitSwarm feature and to do that you need to register running Koding as a new application to your running GitSwarm application. Follow these steps to enable this integration.
Redirect URI should be http://gitlab.127.0.0.1:8090/-/oauth/gitlab/callback which again you need to replace 127.0.0.1 with your instance public IP.
Take a copy of Application ID and Secret that is generated by the GitSwarm application, we will need those on Koding Part of this guide.
Koding can take actions based on the events generated by GitSwarm application. This feature is still in progress and only following events are processed by Koding at the moment;
All system events are handled but not implemented on Koding side.
To enable this feature you need to provide a URL and a Secret Token to your GitSwarm application. Open your admin area on your GitSwarm app from http://127.0.0.1:3000/admin/hooks and provide URL as http://gitlab.127.0.0.1:8090/-/api/gitlab which is the endpoint to handle GitSwarm events on Koding side. Provide a Secret Token and keep a copy of it, we will need it on Koding Part of this guide.
(replace 127.0.0.1 with your instance public IP)
If you followed the steps in GitSwarm part we should have followings to enable Koding part integrations;
Application ID and Secret for OAuth integrationSecret Token for system hook integrationNow we need to configure Koding with all this information to get things ready. If it's already running please stop koding first.
Replace followings with the ones you got from GitSwarm part of this guide;
cd koding
docker-compose run \
--service-ports backend \
/opt/koding/scripts/bootstrap-container build \
--host=**YOUR_IP**.xip.io \
--gitlabHost=**GITLAB_IP** \
--gitlabPort=**GITLAB_PORT** \
--gitlabToken=**SECRET_TOKEN** \
--gitlabAppId=**APPLICATION_ID** \
--gitlabAppSecret=**SECRET**Alternatively you can update gitlab section on config/credentials.default.coffee like following;
gitlab =
host: '**GITLAB_IP**'
port: '**GITLAB_PORT**'
applicationId: '**APPLICATION_ID**'
applicationSecret: '**SECRET**'
team: 'gitlab'
redirectUri: ''
systemHookToken: '**SECRET_TOKEN**'
hooksEnabled: yesand start by only providing the host;
cd koding
docker-compose run \
--service-ports backend \
/opt/koding/scripts/bootstrap-container build \
--host=**YOUR_IP**.xip.io \Once you restarted your Koding and logged in with your username and password you need to activate oauth authentication for your user. To do that
http://gitlab.**YOUR_IP**.xip.io:8090/Home/my-accountThis will redirect you to your GitSwarm instance and will ask your permission ( if you are not logged in to GitSwarm at this point you will be redirected after login) once you accept you will be redirected to your Koding instance.
From now on you can login by using SIGN IN WITH GITLAB button on your Login screen in your Koding instance.