BigW Consortium Gitlab

koding.md 8.17 KB
Newer Older
1 2
# Koding & GitLab

3 4
> [Introduced][ce-5909] in GitLab 8.11.

5 6 7 8 9 10 11 12 13 14 15 16
This document will guide you through installing and configuring Koding with
GitLab.

First of all, to be able to use Koding and GitLab together you will need public
access to your server. This allows you to use single sign-on from GitLab 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
17
[Kite](https://github.com/koding/kite), that we have written at Koding. Which is a
18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34
microservice framework that allows you to develop microservices easily.

## Requirements

### Hardware

Minimum requirements are;

  - 2 cores CPU
  - 3G RAM
  - 10G Storage

If you plan to use AWS to install Koding it is recommended that you use at
least a `c3.xlarge` instance.

### Software

35 36
  - [Git](https://git-scm.com)
  - [Docker](https://www.docker.com)
37 38 39 40 41 42
  - [docker-compose](https://www.docker.com/products/docker-compose)

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.

43
Required services are:
44

45 46 47 48
- **PostgreSQL** - Kontrol and Service DB provider
- **MongoDB**    - Main DB provider the application
- **Redis**      - In memory DB used by both application and services
- **RabbitMQ**   - Message Queue for both application and services
49 50 51 52 53 54 55 56 57 58 59 60 61 62 63

which are also provided as a Docker container by Koding.


## Getting Started with Development Versions


### Koding

You can run `docker-compose` environment for developing koding by
executing commands in the following snippet.

```bash
git clone https://github.com/koding/koding.git
cd koding
64
docker-compose -f docker-compose-init.yml run init
65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241
docker-compose up
```

This 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 GitLab integration in the
configuration. To make things in order it's recommended to create the `gitlab`
team first thing after setting up Koding.


### GitLab

To install GitLab to your environment for development purposes it's recommended
to use GitLab Development Kit which you can get it from
[here](https://gitlab.com/gitlab-org/gitlab-development-kit).

After all those steps, gitlab should be running on `localhost:3000`


## Integration

Integration includes following components;

  - Single Sign On with OAuth from GitLab to Koding
  - System Hook integration for handling GitLab events on Koding
    (`project_created`, `user_joined` etc.)
  - Service endpoints for importing/executing stacks from GitLab to Koding
    (`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 GitLab on. Better to use a domain but a static IP
is also fine.

For IP based installation you can use [xip.io](https://xip.io) service which is
free and provides DNS resolution to IP based requests like following;

  - 127.0.0.1.xip.io              -> resolves to 127.0.0.1
  - foo.bar.baz.127.0.0.1.xip.io  -> resolves to 127.0.0.1
  - and so on...

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.


### GitLab Side

You need to enable Koding integration from Settings under Admin Area. To do
that login with an Admin account and do followings;

 - open [http://127.0.0.1:3000/admin/application_settings](http://127.0.0.1:3000/admin/application_settings)
 - scroll to bottom of the page until Koding section
 - check `Enable Koding` checkbox
 - provide GitLab 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.


#### Registering Koding for OAuth integration

We need `Application ID` and `Secret` to enable login to Koding via GitLab
feature and to do that you need to register running Koding as a new application
to your running GitLab application. Follow
[these](http://docs.gitlab.com/ce/integration/oauth_provider.html) 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 GitLab
application, we will need those on _Koding Part_ of this guide.


#### Registering system hooks to Koding (optional)

Koding can take actions based on the events generated by GitLab application.
This feature is still in progress and only following events are processed by
Koding at the moment;

  - user_create
  - user_destroy

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
GitLab application. Open your admin area on your GitLab app from
[http://127.0.0.1:3000/admin/hooks](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 GitLab 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)_


### Koding Part

If you followed the steps in GitLab part we should have followings to enable
Koding part integrations;

  - `Application ID` and `Secret` for OAuth integration
  - `Secret Token` for system hook integration
  - Public address of running GitLab instance


#### Start Koding with GitLab URL

Now we need to configure Koding with all this information to get things ready.
If it's already running please stop koding first.

##### From command-line

Replace followings with the ones you got from GitLab part of this guide;

```bash
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**
```

##### By updating configuration

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: yes
```

and start by only providing the `host`;

```bash
cd koding
docker-compose run                              \
  --service-ports backend                       \
  /opt/koding/scripts/bootstrap-container build \
  --host=**YOUR_IP**.xip.io                     \
```

#### Enable Single Sign On

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

 - Navigate to Dashboard on Koding from;
   `http://gitlab.**YOUR_IP**.xip.io:8090/Home/my-account`
 - Scroll down to Integrations section
 - Click on toggle to turn On integration in GitLab integration section

This will redirect you to your GitLab instance and will ask your permission (
if you are not logged in to GitLab 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.
242 243

[ce-5909]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5909