Getting Started

Try out the API Portal in the following simple steps.


Introduction

This introduction to the API Portal we provide will guide you to deploy an API Portal like the one we keep for demo purposes at wicked-demo.haufe.io.

The wicked API Portal is designed to run within docker. While it would be perfectly possible to run the API Portal without docker, we at Haufe firmly believe that it is not worth the effort. We have designed a deployment you can just use off the shelf, including guidelines on how to

  • Deploy
  • Update
  • and Operate

your API Portal and the API Gateway (Mashape Kong) which is used to proxy the APIs.

The following steps assume that you are familiar in using a bash type shell, and that you have a running git installation. On Linux/Mac OS X this should be present out of the box (if you are a developer). On Windows, using either the Ubuntu bash Windows subsystem, or plain "Git bash" (cygwin) should work fine.

Note: The following guide is not suitable as a starting point for your own configuration, but is rather meant as a demo configuration. The documentation contains more information on how to get you started with your own APIs.

 

 

Step 1: Prerequisites - Docker

The only prerequisites for this getting started guide is that you have access to a the docker command line and a Docker host. If you haven't already installed Docker, go ahead and do that first. It will work both on Windows and Mac OS X machines without problems, best using docker 1.12 or later.

The API Portal will - for evaluation purposes - happily run on your local machine, or on any docker host which you have set up docker-machine to talk to. Make sure you are using version greater than or equal to 1.12 (compose 1.8.0) when deploying the API Portal, as we are using features of Docker which are not available before that. Also make sure you have a recent docker-compose installed; if you haven't, click the link above and get it before proceeding. If you are using the Docker ≥1.12 for Mac OS X or Windows, docker-compose will already be installed on your machine.

Get Docker »

Step 2: Clone the Sample Deployment Repository

Deploying the API Portal is equivalent to running a docker-compose.yml file. Get a sample configuration repository from the Haufe-Lexware Github Repository:

$ git clone https://github.com/Haufe-Lexware/wicked.deploy.sample
...
$ cd wicked.deploy.sample

Make sure you have a docker host at hand you can deploy to. If you have just installed docker on your local machine, this will be the case, and you just have to call either the "Docker Quickstart Terminal" or - with more recent installations - simply the Terminal. Check that everything works:

$ docker --version
Docker version 1.12.0, build 8eab29e
$ docker-compose --version
docker-compose version 1.8.0, build f3628c7
$

 

 

Step 3: Create /etc/hosts entries

 

Open up your /etc/hosts (Linux/Mac OS X, on Windows: C:\Windows\System32\drivers\etc\hosts) file in an editor (this step will be different on Linux, Mac OS X and Windows, please google if unclear) and add the following two lines:

127.0.0.1   portal.local
127.0.0.1   api.portal.local

Note: You may need to sudo to change that file; on Windows you will need to edit the hosts file as Administrator. Check that you can ping your machine using both DNS names:

$ ping portal.local
PING portal.local (127.0.0.1): 56 data bytes
64 bytes from 127.0.0.1: icmp_seq=0 ttl=64 time=0.098 ms
...
$ ping api.portal.local
PING api.portal.local (127.0.0.1): 56 data bytes
64 bytes from 127.0.0.1: icmp_seq=0 ttl=64 time=0.098 ms
...

 

Step 4: Deploy

We are now almost set to deploy the API Portal. We just have to define some environment variables and call docker-compose.

$ source ./env.sh
$ docker-compose up -d
...

This will take a little while, mostly because docker has to download the container images used for the portal. Depending on your internet connection speed, you can expect this to take from two to ten minutes (the images are around 1.5 GB in size in total).

 

 

Step 5: Log in

Navigate to your API Portal at https://portal.local and start playing around. The sample configuration has a preconfigured admin user with the following credentials:

  • User email: admin@foo.com
  • Password: wicked

 

Screenshot

Read more in the documentation, e.g. on how to use the sample portal.

To stop and deallocate the local API Portal, issue the following command:

$ docker-compose down

Back to top

© 2016-2017 Haufe-Lexware GmbH & Co. KG, www.haufe-lexware.com, www.haufe.de, www.lexware.de, www.haufe-akademie.de