AdroitLogic IPS, Part 2: Installation (Getting the Beast Up and Running)

Okay, all the fancy words aside, what would it take for me to actually try this thing out?

A fully-fledged Kubernetes or OpenShift cluster?
An AWS account with a valid credit card?
A briefcase of cash to pay for support?

Fortunately, none of the above.

With the DIY IPS Installer you can start up a simple demo IPS set-up on your own machine. All you need is VirtualBox and an internet connection!

Hmm, sounds cool…​ How do I start?

First of all, ensure that you have the prerequisites in place, to avoid unpleasant surprises later on.

  • Memory : at least 6GB free
  • Disk space : at least 6GB free
  • Operating system : Mac OS X or Linux x64
  • VirtualBox : v5.1.8 or above
  • Internet connectivity : around 2GB of bandwidth quota

Head over to our IPS product page, read all the features, benefits and stuff (kidding) and click the Try Now! button.

We have IPS ready-made for Linux and Mac, so pick your choice and click Download.

If you’re Windows-only, your journey unfortunately ends here 🙁 at least until we come up with a build for Windows, where we’re facing a few hiccups right now; write to us if you’re interested in getting IPS for Windows, and we’ll give it another go!

Oh ho! A contact form!

Well, we’d like to know a bit about you so that we can know more about your requirements and possibly help you out with a better solution if it comes to that. Nothing more than a friendly follow-up (and, should you decide to opt in, an occasional integration newsletter). No spam, that’s a promise!

Okay, okay, I’m filling it. Wait, what’s this “Docker ID” thing?

IPS has some proprietary Docker images, for which we need to grant you access. Hence we need you to have a Docker Hub account (or create one for free if you don’t have one). Enter your Docker ID or username (one that appears on the top right once you log in to the account, or on your homepage’s URL (e.g. mine is https://hub.docker.com/u/malithj/, hence my Docker ID is malithj) in your browser’s address bar) in the corresponding field.

Even if you have no idea of what “Docker” or “Docker image” means, just create an account and give us the username, and we’ll take care of the rest. The rest of the fields should be self-explanatory, should you decide to fill them all 🙂

Done and dusted, and submitted. What’s next?

You shall receive an email from license@adroitlogic.com with a link to download the installer and a client.key.properties file attachment.

Click the link, and wait for the download to complete. It would be around 50 MB in size.

(By the way, In case you didn’t receive the email or found that it had ended up in your spam/junk folder, please inform us immediately at info@adroitlogic.com!)

Extract the downloaded zip file to someplace safe, and open it in a file browser. You will see the following content:

  • bin: contains the installer itself (ips_installer), and a Kubernetes CLI client (kubectl) for any troubleshooting requirements
  • conf: contains a license directory where we would be placing our “client key” from the email, and an images.json file which specifies some not-to-worry-about configurations
  • lib: this is where we place any third party artifacts (e.g. a MySQL Java client library) needed for IPS

First, add the kubectl binary to your system path so that the installer can find it when required. On Linux (and Mac) you could easily do this by adding a new PATH entry in your ~/.bashrc or ~/.profile (or even /etc/profile or /etc/environment if you are installing IPS for multiple users):

export PATH=$PATH:<path where you extracted ips installer>/bin/kubectl

or, for an imaginary friend johndoe who ended up downloading the zip into his personal downloads directory,

export PATH=$PATH:/home/johndoe/Downloads/ips_installer_17.07_linux/bin/kubectl

If you prefer not to do this, you could always run the above command in the current command shell, and proceed with the same shell when running the installer.

Now, download the client.key.properties file from the email which was sent confirming your download and place it in conf/license directory (so that it would now contain 2 files.)

Next, download the MySQL client library from here, unzip it and place the mysql-connector-java-5.1.38-bin.jar inside lib. This will be used for all database operations inside IPS.

Wait…​ Why the heck do I have to download the MySQL JAR? Why don’t you ship it with the installer?

Unfortunately, Oracle’s licensing model associated with MySQL prevents us from shipping it with our product. Hence the most logical way is for you to download it on your own (with your own consent); in fact this is exactly how others like Confluence have decided to play the game, and rest assured that you (the user) are not violating any terms, conditions or licenses in playing it this way.

Done? Then you’re all set!

Completed folder structure of IPS

Head over to the bin directory in your command shell:

cd <path where you extracted ips installer>/bin/

or, for our imaginary friend,

cd /home/johndoe/Downloads/ips_installer_17.07_linux/bin/

And type ips_installer start and press Enter (or hit Return, whatever works for you)!

The installer will first download a “Minikube ISO” (unless you have run Minikube or IPS installer on the same machine before), and proceed with creating a Minikube virtual machine which will eventually be transformed into your own IPS instance.

Patience. Long pause ahead.

After the (first) long pause, you’ll be prompted with something like:

This will download around 1437 MB from internet including required Docker Images to start IPS
Do you wish to continue (Y/n) :

Now there’s the catch; though the installer itself was less than 60 MB in size, the Docker images are the ones that really do the magic (and hence weigh more). But don’t worry, this download is one-time (unless you somehow happen to delete the VM and re-create it). So go ahead; type Y and press Enter.

We need your Docker Hub credentials entered in product download form to download required Docker Images. Your credentials will be discarded once the installation completed
Docker Hub account :

Okay, it’s just the username (in case of the previous example, malithj)…​

johndoe<Enter>

Docker Hub password :

That’s it! I quit! Why the **** are you asking for my password?!

Earlier, when you filled your Docker hub ID into the contact form, we secretly granted you access to our secret ingredient — ​the IPS Docker images. Now, in order to access them, we need to authenticate Minikube’s Docker process (daemon) to act on behalf of you so that it can download those images. This is why we need your login info. We won’t store your username or password under any circumstances, or transmit it to anywhere other than Docker Hub (more precisely the Docker daemon) itself, you have my word on that.

If you are still uncomfortable with providing the password, there’s a small hack you could do: while the installer is waiting for the password, in a separate shell, run ips_installer ssh to log in to the VM, and run the following sequence of commands manually:

  1. docker login (which will again ask for your username and password, but this time it will be the Docker process (daemon) itself, not us; if you cannot trust the daemon, who else could you trust?)
  2. docker pull adroitlogic/configserver:17.07
  3. docker pull adroitlogic/ipsweb:17.07
  4. docker pull adroitlogic/ips-worker:17.07

And once the above commands have finished executing, switch back to the installer and provide a fake password.

Once you provide the credentials, the installer will start pulling (downloading) images into the machine, which would take a considerable time (depending on your internet connection bandwidth). So go and help yourself to some snacks and coffee.

When you are back, you shall see the following lines printed by the installer:

Fetching license from license server
Successfully transferred the license to VM
Fetching Docker Images to setup IPS
Pulling image gcr.io/google_containers/exechealthz:1.0
Image exechealthz successfully pulled
Pulling image gcr.io/google_containers/kube2sky:1.11
Image kube2sky successfully pulled
Pulling image gcr.io/google_containers/etcd:2.0.9
Image etcd successfully pulled
Pulling image gcr.io/google_containers/skydns:2015-03-11-001
Image skydns successfully pulled
Pulling image mysql/mysql-server:5.7.17
Image mysql-server successfully pulled
Pulling image elasticsearch:5.1.1
Image elasticsearch successfully pulled
Pulling image adroitlogic/configserver:17.07
Image configserver successfully pulled
Pulling image adroitlogic/ipsweb:17.07
Image ipsweb successfully pulled
Pulling image adroitlogic/ips-worker:17.07
Image ips-worker successfully pulled
Pulling image adroitlogic/kube-addon-manager-amd64:1.0
Image addon-manager successfully pulled
Kubectl is now configured to use the cluster.

Voila! That’s it!

Now run

ips_installer ip

to get hold of the IP address of the VM. It would most probably be something like 192.168.99.100.

Now open your favourite web browser, type in https://, followed by the above IP address, followed by :30080 (e.g. https://192.168.99.100:30080) and press Enter.

OK, what the heck is this?

We have a self-signed certificate for the IPS web console, which is why the browser is creating a bit of a fuss. For now, click Show Advanced > Proceed to 192.168.99.100 (unsafe).

In a few seconds, ye shall see the IPS login page. Login is easy, just type admin for both username and password, and click Sign In.

Within milliseconds you will be staring at the main IPS dashboard, with some fancy health and system status indicators. If the 3 indicators at the top of the page (Database, Platform API and Configuration Server) are all green, it’s party time!

(If any, especially the Configuration Server, are red, wait for about a minute to see if it gets recovered.)

Congratulations! You have just installed IPS on your own system.

But that’s only the beginning…​

Now you can confidently

  • head over to one of our ready-made, 2-minute sample projects that could be tried out right away
  • read more about IPS, at our simple, yet comprehensive documentation space
  • run to your colleagues or team lead, throwing your hands in the air and crying out “It works!”

Or, if you’re too tired and would like to start off later on, just run an ips_installer stop. Everything would be exactly as you left them after you run ips_installer start the next day.

Leave a Reply