CODEOWNERS API

Pre-requisites

• Install Docker Desktop
• Install Homebrew
• Install nvm and Node.js >= v16
• Install ejson (more on ejson workflow in the docs)

$ curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.1/install.sh | bash
$ nvm list-remote 16
$ nvm install v16.X.X
$ brew tap shopify/shopify && brew install ejson

Getting Started

• Copy the "EJSON Key (Development)" from 1Password into /opt/ejson/keys/<key-id>
• Copy the NPM_TASKFORCESH_TOKEN from 1Password into your shell environment:
  • ex. echo 'export NPM_TASKFORCESH_TOKEN=<token value>' >> ~/.zshenv
• Run docker-compose -f docker-compose.development.yml up -d db redis to start PostgreSQL and Redis
  • You can skip the -f option with a simple soft-link sudo ln -s docker-compose.development.yml docker-compose.yml
• Ensure database is up (docker-compose logs db --follow to check) and migrate/seed the database:
  • npm run decrypt:dev && npm run build && npm run db:setup

Developing

Start the server in dev mode, npm run dev (this includes a file watch for your changes). Happy hacking!

Generate an SDK for the API

Install the openapi-generator-cli

npm install @openapitools/openapi-generator-cli -g

Run npm run build:sdk to build all three sdks (typescript-node, typescript-fetch, typescript-ruby) and find them under the sdk folder.

Or to build them separately, run npm run sdkgen:typescript-node, npm run sdkgen:typescript-fetch or npm run sdkgen:ruby.

If you don't have a JAVA runtime environment, you will be instructed to install it. You can run the command again once it's done.

Add template for target platform

To generate an API with any other language, first make sure the generator supported (see https://openapi-generator.tech/docs/generators/). We need to modify the template file so that the constructors of the sdk will set the version headers appropriately and accept the Api Key as a parameter.

openapi-generator-cli author template -g generator-name -o src/shared/documentation/templates/generator-name

In the new templates folder, look for the mustache file(s) that define the constructor and change the constructors as needed. You may delete the files that do not need to be changed. Once the template is modified, run the command with the new platform name. Add the new command to the npm package as an individual command and add it to the build:sdk command.

Configuration

Environment-specific configuration is now packaged as part of the application and encrypted using ejson. You can still override / configure the application using a .env file or explicitly setting ENVAR1=somevalue as part of the start command. For development, you need only concern yourself with src/config/config.development.ejson.

Adding new Configuration

To add new configuration variables, create the appropriate keys in the config.<environment>.ejson files, then encrypt them ejson encrypt src/config/config.<environment>.ejson. If the key does not sensitive or secret information, it should be prefixed with an underscore (ex. "_MY_CONFIG_VARIABLE": "server1.com").

SSL / HTTPS

Check out the [README-https.md] for more detail. To set up HTTPS on your local server is easy:

1. Ensure you have dev.echolayer.com as localhost entry in your /etc/hosts file:
   • echo "127.0.0.1 dev.echolayer.com" | sudo tee -a /etc/hosts
2. Install NGINX (uses Homebrew): npm run nginx:install
3. Configure NGINX: npm run nginx:configure
4. You're done! curl https://dev.echolayer.com

The SSL certificate expires every 90 days, but is renewed continually on a Digital Ocean droplet. Get the certificates from:

• /etc/letsencrypt/live/dev.echolayer.com/fullchain.pem
• /etc/letsencrypt/live/dev.echolayer.com/privkey.pem

Docker

You can build a runnable docker container with npm run build:docker. To run the container in the local Docker Compose network:

# Grab dev key pair from 1Password
export EJSON_PUBLIC_KEY=...
export EJSON_PRIVATE_KEY=...
npm run start:docker

Recommended: to debug the built image, you can use dive to inspect the filesystem, layer by built layer.

Signing up

By default when you sign up in development, it will not automatically register you (you will not receive the email, but it will be printed on the console for you to copy paste and visit). If you want to skip this step, set AUTO_VERIFY_USERS=true in your working .env.

Test Suite

Tests live in tests/, run them with npm t or npm test. We use:

• Mocha as test runner
• Chai for expectations
• Chai HTTP for HTTP tests
• ts-mockito for mocking, verification, etc.

Integration Tests

In order to run integration tests, you'll need a Github Personal Access Token GITHUB_PAT, you can create one here.

Database Administration

The PostgreSQL data is stored (volume mounted into the Docker container) in your project directory under .pgdata; it is a git ignored. This gives you the flexibility to manage different copies of your database with different schema versions or data sets. If the .pgdata directory is missing, starting the db Docker container will recreate and reinitialize the entire database. You can keep a copy of your current database by renaming the directory:

$ docker-compose stop db
$ mv .pgdata .pgdata.original-branch
$ git checkout -b a-new-branch
$ docker-compose up db -d

Similarly, you can restore that copy by swapping the directories around:

$ docker-compose stop db
$ mv .pgdata .pgdata.a-new-branch
$ git checkout original-branch
$ mv .pgdata.original-branch .pgdata
$ docker-compose up db -d

pgAdmin

pgAdmin is useful for interacting with the database, start it with docker-compose up -d pgAdmin:

• Visit http://localhost:8080:
  • Login: admin@echolayer.com
  • Password: password
• Create a server in pgAdmin:
  • Host: db (this is the PostgreSQL hostname within the docker-compose network)
  • Port: 5432
  • User: echolayer
  • Password: password

Database ORM & Migrations

We use TypeORM.

• Database setup: npm run db:setup
• Generate migration: npm run db:migration:generate --migration_name=<your migration name>
  • PostgreSQL server must be running (docker-compose up -d db)
• Reset database: npm run db:reset THIS WILL NUKE YOUR CURRENT DATASET

Seeding the database

In order to seed the database:

• create an account by signing up on our web app - http://localhost:3005
• create an org by specifying an org name
• run npm_config_org_name="<your org name>" npm run db:seed to seed your org with data

CI/CD

Continuous Integration is achieved with GitHub Actions. Every commit pushed to GitHub runs the test suite automatically, and is required to pass to merge into development, staging, production, and main branches. Have a look at npm_test.yml for more detail.

Successful merges to development, staging, production, and main all produce a Docker image published to the Github Container Registry. Check out publish_image.yml to see how. The available images are tagged as such:

• ghcr.io/useecholayer/echolayer-api:<git-sha> the short-form git SHA of the merged commit
• ghcr.io/useecholayer/echolayer-api:<branch-name> the latest merge into the respective persistent branch (ex. development)

Troubleshooting

I can't <build the app | run the app | run the tests>!

npm run decrypt:dev

echolayer-api@1.x.x decrypt:dev ejson decrypt -o src/config/config.development.json src/config/config.development.ejson

Decryption failed: couldn't read key file (open /opt/ejson/keys/: no such file or directory)

If this error occurs, it's because you don't have the appropriate ejson key. Grab it from 1Password and put it in your /opt/ejson/keys/ directory. The file name is the public key ("username" in 1Password), while the content of the file is the private key ("password" in 1Password).

Error: ENOENT: no such file or directory, open '../id_rsa_priv.pem'

Can't find the .pem file? * Run npm run build