Skip to content

Latest commit

 

History

History
215 lines (162 loc) · 10.8 KB

INSTALL.md

File metadata and controls

215 lines (162 loc) · 10.8 KB
Raw

Table of Contents generated with DocToc

Installation

Note on migration

We have updated MeteorJS version from 1.5.2 to 1.8. If you need to update the installation which is based on Meteor 1.5.2 to version which uses Meteor 1.8, you need to run MongoDB migration. More information here: https://docs.mongodb.com/manual/release-notes/3.6-upgrade-standalone/

The issue is that new version of MongoDB which comes with MeteorJS version 1.8 has new database engine; Procedure is to 1) mongo dump 2) upgrade to version with meteor 1.8 3)meteor reset 4) mongo restore

Note on different Umbrella versions

We have forked the NREL/api-umbrella: https://github.com/apinf/apinf-umbrella; We have removed MongoDB from the umbrella image. You should deploy MongoDB in another container/machine and configure APInf Umbrella to use that external instance of MongoDB.

From Source Code

  1. Clone APInf fork of umbrella: https://github.com/apinf/api-umbrella and follow the instructions in that repo. Easiest way to get started is to follow "With Docker Compose" section below and when you got that working, start exploring options.
  2. Install Meteor.js
  3. Clone Apinf, a new folder "platform" created. cd into that platform:
$ cd platform/
xxyy@ThinkPad-T430s:~/platform$
  1. Run meteor npm install - using meteor instead npm makes sure the same npm is used that comes with meteor distribution:
~/platform$ meteor npm install
  1. Type meteor in the project directory:
ThinkPad-T430s:~/platform$ meteor

With Docker

  1. Run API-umbrella container http://api-umbrella.readthedocs.io/en/latest/getting-started.html#running-with-docker
  2. Obtaining API Key and Authentication token. You can obtain the Authentication Token and API Key from the API Umbrella platform by following instructions in the Getting Started and API Umbrella Admin API documentation.
  3. Run APInf container docker run -p 8080:80 -e MONGO_URL=mongodb://localhost:27017/your_db -e MAIL_URL=smtp://some.mailserver.com:25 -e ROOT_URL=http://YOUR_SITE_DOMAIN apinf/platform:latest
  4. Configure APInf

Configure APInf

Register a new admin account. The first user will become Admin.

  1. Signup to the APInf http://YOUR_SITE_DOMAIN/sign-up
  2. Login to the APInf web admin http://YOUR_SITE_DOMAIN/sign-in
  3. Fill APInf settings http://YOUR_SITE_DOMAIN/settings

With Docker Compose

Have a server with minimum of 2 GB ram and 20 GB disk. One core should be ok. Get a FQDN name for server - dont use Amazon AWS as we are using Let's Encrypt and they have blacklisted autogenerated AWS domain names. Or then you have to assign name on your own.

Make sure that you have github application created for this domain. You need this in step 7. Here is a good read on how-to: https://auth0.com/docs/connections/social/github authorization callback url needs to be like https://YOUR_SITE_DOMAIN:3002 make sure to include the port.

  1. Create "docker-compose.yml" file on your server and copy content from docker-compose.yml.
  2. In the same folder create file "docker/api-umbrella/config/api-umbrella.yml" based on example "docker/api-umbrella/config/api-umbrella.yml.example". ATTENTION: Replace "example.com" on YOUR_SITE_DOMAIN for keys "ssl_cert" and "ssl_cert_key".
  3. Create file "docker/env.apinf" based on example "docker/env.apinf.example".
  4. Create file "docker/env.ssl" based on example "docker/env.ssl.example".
  5. Modify api-umbrella.yml to have github credentials (client_id and client_secret). Github only login is enabled at this time. If you have the skills, by modifying the api-umbrella.yml you can enable other login methods. Make sure also to modify the "initial_superusers" as you need to be able to login as super user.
  6. Run docker-compose up -d. The first launch of it will be slow because (take couple of minutes) of the DH parameter computation and configure Let's Encrypt certificate.
  7. Visit https://YOUR_SITE_DOMAIN:3002 to verify that proxy is running
  8. Visit https://YOUR_SITE_DOMAIN:3002/admin/login and log in.
  9. API key and Auth token you can get from umbrella, so login if you have not done so. The "Auth Token" need to come from admin, so on the right hand side pulldown menu (looks like a gear) pick "account or my account", there you can get the "Admin API token" (referred as Auth token later on). To get the API key, you need to go to https://YOUR_SITE_DOMAIN:3002/signup and fill the form. Copy the Auth token and API key. You need those in the next step.
  10. Login to apinf platfrom https://YOUR_SITE_DOMAIN. When signing up as 1st user you get admin rights. To define proxy settings: Under your account pulldown menu, choose "proxy", click "add proxy" and fill in the following details:
  • name: whatever you like
  • description: whatever you like
  • type: apiUmbrella following fields are revealed as you pick the "type":
  • url: https://YOUR_SITE_DOMAIN:3002
  • API KEY: - from umbrella, step 9
  • AUTH TOKEN: - from umbrella, step 9
  • ElasticSearch: "http://elasticsearch.docker:9200" -> hit save. Now you are ready to add your 1st API.
  1. Add API backend https://YOUR_SITE_DOMAIN/api/new

You can use for example http://restcountries.eu/#api-endpoints-name as a test API. Note! It's better to pass the x-api-key as a header than in the URL! That's it. Now you can go to and check the Quick start, watch the video and enjoy!

A Few random notes: API Key and Auth token need to be from the same user. If you get into trouble, send us an email: [email protected] or raise an issue.

mail

The mail object contains a username and password for the Mailgun service. You will need to register with Mailgun. Once registered, you can use your 'sandbox' domain credentials in a development environment or a custom domain in production:

  • Default SMTP Login
  • Default Password

For up-to-date instructions, refer to the Mailgun Help Center

elasticsearch

Elasticsearch takes a host value that contains the host and port of the API Umbrella ElasticSearch instance. In a standard API Umbrella deployment, this will be the same as the API Umbrella base URL, with port number 14002. Note: Elastic REST API may be exposed via HTTP instead of HTTPS, so double check the protocol.

githubConfiguration

The Github configuration takes two values, a Client ID and Secret key. You can obtain these values by setting up a Github application from your Github user account.

Development installation with Docker

Install Docker

Review the Docker installation instructions for your Operating System:

Optionally add your user to the docker group.

Install Docker Compose

You will also need to install Docker Compose.

Ubuntu

Install Docker Compose on Ubuntu Linux with the following command:

$ sudo apt install docker-compose

Edit API Umbrella configuration

API Umbrella configuration should be stored in

  • [project-root]/docker/api-umbrella/config/api-umbrella.yml

You can create api-umbrella.yml based on the example:

  • [project-root]/docker/api-umbrella/config/api-umbrella.yml.example

Prepare APInf image

  1. Run application containers (in first time it will build image):
$ docker-compose up
  1. Add apinf.dev and api-umbrella.dev hosts entry to /etc/hosts file so you can visit them from your browser.

See Docker IP address (step only for Mac)

$ docker-machine ip
=> 127.0.0.1

Set hosts

Then add the IP to your /etc/hosts:

127.0.0.1 apinf.dev api-umbrella.dev

Now you can work with your app from browser by visit http://apinf.dev:3000

Create API Umbrella credentials

  1. Login to the API Umbrella web admin https://api-umbrella.dev/admin/login
  2. Signup to the APInf http://apinf.dev:3000/sign-up
  3. Login to the APInf web admin http://apinf.dev:3000/sign-in
  4. Fill API Umbrella settings http://apinf.dev:3000/settings :

Debugging containers with docker exec

This can be accomplished by grabbing the container ID with a docker ps, then passing that ID into the docker exec command:

$ docker ps
CONTAINER ID        IMAGE
ce9de67fdcbe        apinf/platform:latest
$ docker exec -it ce9de67fdcbe /bin/bash
root@ce9de67fdcbe:/#

Add alias to bash:

alias apinf_web='docker exec -it `docker ps | grep web | sed "s/ .*//"` /bin/bash'

Building Docker Images

Building Images

To build packages for the current APInf version:

$ docker build -t apinf/platform:INSERT_VERSION_HERE .
$ docker tag apinf/platform:INSERT_VERSION_HERE apinf/platform:latest

Pushing to Docker Hub

To publish the new images to our Docker Hub repository:

$ docker push apinf/platform:INSERT_VERSION_HERE
$ docker push apinf/platform:latest