Skip to content

Getting Started V Alpha

Jump to bottom
Muhammad Arief Rahman edited this page Jun 21, 2020 · 1 revision

Download the latest release

In this page, you will be guided about how to use altair. Before proceeding, please download the latest release here.

Prerequisites

Before you can run altair, please install mysql or mariadb.

The configuration

All of altair's configuration, databases and application port are written in .env file that included in the release pack. Please fill the config to match your local env.

# App config
APP_ENV=local
APP_PORT=1304
ACCESS_TOKEN_TIMEOUT=24h
ACCESS_GRANT_TIMEOUT=2h

# Database configuration
DATABASE_HOST=localhost:3306
DATABASE_NAME=altair_development
DATABASE_USERNAME=root
DATABASE_PASSWORD=
DATABASE_CONN_MAX_LIFETIME=120s
DATABASE_MAX_IDDLE_CONN=100
DATABASE_MAX_OPEN_CONN=100

# Basic auth configuration
BASIC_AUTH_USERNAME=altair
BASIC_AUTH_PASSWORD=eaglethatflyinthebluesky

PROXY_HOST=www.local.host

EXAMPLE_USERS_SERVICE_HOST="www.local.host:3000"

After setting the databases config, run the migration by doing this command:

./altair migrate

You should see three tables in your databases now. oauth_applications, oauth_access_tokens, oauth_access_grants.

Routes Config

After run the migration, you can open the routes config which use to forward the request from altair to respective services. The config should looks like this.

# This is the sample of route config for port forwarding
# name: <string>                      - The name of the service to be addressed
# auth: <string>                      - Authentication method. Available: oauth, none. Default: none
# prefix: <string> [format: ^\/.+]    - The prefix of the services routes. Example: /users, /products & /stores
# host: <string>                      - The host of the services to be addressed. Example: localhost:3000
# path: <array[hash]>                 - The list of path in users services
#   <example>
#     /me: {}                         - Then altair will be forwarding the request into example.com/users/me with any method

name: users
auth: none
prefix: /users
host: {{ env "EXAMPLE_USERS_SERVICE_HOST" }}
path:
  /me: {}
  /profiles/:id: {}

Each services should be written in different config, let's says that you have 2 services that want to be forwarded from altair. Then you should create 2 yaml config in your routes. example:

routes/
  service-a.yaml
  service-b.yaml

Also there are dynamic variable in the routes config like {{ env "XXX" }} which mean you can call environment variables of XXX and then will be generated in the routes config.

Download and run the dummy services, if you don't have any real services.

You can download this binary to run dummy server based on your OS.

dummy-windows.zip

dummy-linux.zip

dummy-darwin.zip

Run the dummy services. ./dummy.

You should see something when you open:

Run the API Gateway

Now that you already to all the config, then the next thing you should do is run the API gateway. It will be run in your localhost with the port you specified in your env config above, just type this command:

./altair run

When you open this pages, you should receive something like this.

{"message":"OK"}

Then open your service path. at http://localhost:1304/users/me. You should see the response written by your services. Also the route config will forward any method called in that routes, try call patch API in users/profiles/:id.

curl -X PATCH localhost:1304/users/profiles/2

You should see this response

{"id":"2","message":"PATCH success"}

Now that you already installed altair in your local, please do make contribution for this project if you're interested to see what this API Gateway can do.

Clone this wiki locally