Timeless-invest-api NPM

Timeless Investments API Core

This is a new API to handle the timeless investments specific stuff. Enjoy.

System requirements

Node version should be at least 10.16.x
Postgres database with version at least 9.6 (can be run in docker container, see for the instructions below)
NPM
Serverless Framework
GIT client
AWS CLI
AWS IAM Role (Profile) with access to Lambda, S3 and other serverless related services.

Recommended tools

The following tools are optional, but highly recommended for the easiest possible experience.

Docker (version 19.03 or higher)
Docker Compose (version 1.24 or higher)
TypeORM installed in global scope (npm install -g typeorm)

UNIX (Linux or MacOS) environment is preferred.

Getting Started

API Core is build on the top of the Express.js framework and the Postgres database. It can work in two modes (server & serverless) in which app can operate simultaneously.

Server & Serverless

Depends on the mode application is working on, an app has two alternative entry points. The one is server.ts that is handling the standard server connection, and the other one is handler.ts that is handling the serverless connections.

Shared entry point, and the whole application bootstrap is stored in the app.ts file. Due to the specifics on how the database connection are being handled by the AWS Lambda, DB connection layer is also being handled invidually and in a bit different way by server and handler respectively.

Authorizing AWS Services

First you should get the AWS CLI from here and to follow the installation instruction that you can find on the page mentioned above.

Once you have it installed you can either do aws configure to automatically create credentials file.

If you run the aws configure command, two new files will be created at your home directory, those are respectively: ~/.aws/config and ~/.aws/credentials and they will contain content similar to the one below:

.aws/config

[default]
region=eu-central-1
output=json

.aws/credentials

[default]
aws_access_key_id=<keyIdYouProvided>
aws_secret_access_key=<secretKeyYouProvided>

You can also create and modify those files manually to adjust those variables anytime.

Alternatively you can export the proper environment variables so that Serverless can recognize them automatically.

i.e.

export AWS_ACCESS_KEY_ID=<yourAccessKeyId>
export AWS_SECRET_ACCESS_KEY=<yourSecretAccessKey>

It is also important to configure default region, which for Timeless should always be eu-central-1, you can do this either in the config file mentioned above (.aws/config) or in the environment variable.

export AWS_DEFAULT_REGION=eu-central-1

Specifying wrong region might cause the services to not to be visible at first sight in the AWS UI Console

Local development

Assuming you have all the tools mentioned in the system requirement section up and running. To bootstrap and run app locally, following steps are required.

Clone the repository into local directory
Go into the

cd <yourProjectDirectory>

Install dependencies with

npm install

Build initial project

npm run build

Copy the sample environment file and adjust if needed

cp .env.example .env

If you have docker installed you can now create a database container, the access credentials for that database will automatically be taken from environment file, so if you want to make them different from default you should change the .env file (This step is optional but recommended)

npm run up

Disclaimer: Some older docker-compose versions might not properly handle environment variables. Therefore please make sure that version you're using is at least equal to the one specified in system requirements section above.

Run development instance

npm run watch

That should enable development server, being run in watch mode at the port 3000 (port can be adjusted in .env file as well).

File watcher is enabled src directory wide, which means that after each change at the src directory level, server will re-compile automatically.

Migrations & Seeding

Before you can start the actual development, you should sync your database structure, with what's expected by application, to do this you should execute the following command.

npm run migrate

That should run all of pending migrations and to sync the database structure.

Schema syncing

Because the entities within application scope are also described with the proper SQL definition, you can quickly sync the database schema with whatever is specified at the entity level with command:

npm run migrate:sync

Disclaimer: While that command is useful during local development, there's still a requirement to create proper migrations for each of the entity, because only then the structure will be properly adjusted during deployment process.

Seeding

It's also possible to seed the database with random data, what can be helpful for the local development process. If you're running seeds for the first time, you should first execute.

npm run seed:config

Then to run the available seeds you should execute.

npm run seed:run

Running in debug mode

To run the app in debug mode, you should execute command.

npm run debug

Then you can hook into the app with one of the available inspectors.

Running tests

To execute all the available tests, you should run.

npm run test

Manual Deployment

App is pre-built to work with CircleCI to provide a continuous integration flow.

There is however a way to deploy manually using serverless framework. The pre-requirement for a manual deployment is that you should be signed in into Timeless AWS account with the proper roles assigned to your account.

You can find instruction on how to connect to AWS above.

Then once you have it set up you can deploy the package to the specific environment by calling:

sls deploy -s <stageName>

Available stage names are:

dev
staging
prod

It is important to provide a valid stage name flag, as otherwise system won't be able to load proper configuration and the deployment will fail eventually.

Simulating AWS Lambda in Local environment

It is possible to simulate the lambda behaviour instead of running a full server environment by using:

npm run start:offline

Lambda simulation environment has also file watcher enabled so you can develop while keeping the simulation server running.

Connecting to database

If you're using docker image provided with the app, it contains a port redirection rule within its configuration.

That means that you can connect to the localhost on port 54323 with any PostgresSQL supporting tool, and that way you can browse the database structure and execute the queries manually.

Entering database container

If you want, there's also a way to enter into the database container, to do this you have to:

docker exec -it timeless-invest-db bash

Then you can execute any command on the container level, including connecting with postgres client.