📔 Getting started¶

You should be up and running in approx. 3 minutes as long as you already have following software already installed on your machine:

• Node.js
• Docker
• Visual Studio Code (optional)

💻 Install the hlambda server¶

Run the hlambda core stand-alone server using docker

docker run -d -p 8081:1331 --env HLAMBDA_ADMIN_SECRET=demo --name hlambda-server --restart=always -v hlambda_metadata:/usr/src/app/metadata hlambda/hlambda-core:latest

... or run the recommended stack (including Hasura and PostgreSQL ) using docker compose

curl https://www.hlambda.io/raw/code/start/docker-compose.yaml -o docker-compose.yaml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40

version: '3.6'
services:
  postgres:
    image: postgres:12
    restart: always
    volumes:
    - hasura_db_data:/var/lib/postgresql/data
    environment:
      POSTGRES_PASSWORD: postgrespassword
  graphql-engine:
    image: hasura/graphql-engine:v2.3.0-beta.1
    ports:
    - "8080:8080"
    depends_on:
    - "postgres"
    restart: always
    environment:
      HASURA_GRAPHQL_METADATA_DATABASE_URL: "postgres://postgres:postgrespassword@postgres:5432/postgres"
      HASURA_GRAPHQL_ADMIN_SECRET: "demo"
      HASURA_GRAPHQL_ENABLE_TELEMETRY: "false"
      HASURA_GRAPHQL_ENABLE_CONSOLE: "true"
      HASURA_GRAPHQL_DEV_MODE: "true"
      HASURA_GRAPHQL_ENABLED_LOG_TYPES: "startup, http-log, webhook-log, websocket-log, query-log"
      HASURA_GRAPHQL_JWT_SECRET: '{"claims_namespace_path":"$$", "type":"RS256", "key": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAxITajyliCtRFJ9SLPbGs\n8+uL/FZok7big7zQ6lQUJ/3s+MndrLoAhbBZuaf1RKhzWRkizV7I3BetbZ86Iyir\nt0Fp7Lu0Rtyq5GH1O9vAYh5wdp1bQ1t45v/ifR4/Y7C97qq1e1IoelpJxlkEUAN2\nELBMYJ1SGIl94BKgDoF835H68X/s+bKJHoFYPyGPeJbdNFAmYGgrZMleid+bT3Qr\neijMoMuIj1XVMSlN405QWeNqFMGVB73gjhsc3pmyePUBbi67Va+pEBsbexYVsvqO\nynQYlSExbJfHcNL+f0sYrXsGmsPnFji2JWsE3LEUb6Xgab+zmZb+0NcXzMu+t7Hr\ndwIDAQAB\n-----END PUBLIC KEY-----\n"}'
      ACTION_BASE_URL: "http://hlambda-core:1331"
  hlambda-core:
    image: hlambda/hlambda-core:latest
    environment:
      HLAMBDA_ADMIN_SECRET: 'demo'
      HASURA_GRAPHQL_API_URL: "http://graphql-engine:8080"
      HASURA_GRAPHQL_ADMIN_SECRET: "demo"
    ports:
      - "8081:1331"
    restart: always
    volumes:
      - hlambda_metadata:/usr/src/app/metadata

volumes:
  hasura_db_data:
  hlambda_metadata:

... well you should already be up and running, if you access http://localhost:8081 you should be presented with the hlambda server console login screen. If you did not change the commands above the admin secret should be demo. But let's use the hlambda-cli to create our first hlambda app.

🧰 Install Hlambda CLI ¶

$ npm install -g hlambda-cli

This will add Hlambda CLI to your arsenal, now you can use hl, hla or hlambda.

📚 Using Hlambda CLI¶

Check if the console is installed globally, in your terminal you can now run

$ hl

let's initialize new configuration in the new folder test

$ hl i test

change working directory to test

$ cd test

To easily use all hlambda cli commands in the future you can save the admin_secret in the config.yaml manually or just run

$ hlambda config save --admin-secret "demo"

this will edit the config.yaml file and save admin secret value in that file (🧨 please take extra care when commiting config.yaml file to not leak secrets , check Environments section for more details but we suggest you to use env replacer syntax like {{ENV_HLAMBDA_ADMIN_SECRET}} and keeping your secrets in the environemnt variables)

(Optional) You can read the values in the config.yaml by running

$ hlambda config read

(Optional) You can check the structure of the initial demo codebase or edit any part of the code with "Visual Studio Code" before deploying(applying metadata) by running:

$ code .

You can now apply the changes by running

$ hlambda metadata apply

That is it! Enjoy! 😎

🕵️‍♂️ Testing¶

You can use curl to test the API

$ curl -s -X GET http://localhost:8081/demo

or even better hlambda cli for the simple request test

$ hlambda request get demo

$ hlambda console

Happy hacking!

🎊 Bonus¶

All commands have aliases, thus you can run all this even quicker. For example

$ hlambda r g demo

$ hlambda request get demo

you can also get the remote logs by running:

$ hlambda server logs

or with aliases

$ hl s l

📦 Environments¶

If you have multiple deployments of the same app you can now add environments to your hlambda config using hlambda-cli

To add dev environment use

$ hl env add dev

this will add new dev folder environment in ./environments/dev with config.yaml

example content of the ./environments/dev/config.yaml

version: 1
endpoint: "{{ENV_DEV_HLAMBDA_ENDPOINT}}"
admin_secret: "{{ENV_DEV_HLAMBDA_ADMIN_SECRET}}"

this will be used instead of the values in root config.yaml file.

🧨 Important! - You can hardcode but it is the best practice to use env replacer syntax {{ENV_DEV_HLAMBDA_ADMIN_SECRET}} the value will be the one provided in the ENV_DEV_HLAMBDA_ADMIN_SECRET environment variable at the CLI command run-time.

✨ Hlambda cli also supports .env file 😄 so you can create .env file in the root

ENV_DEV_HLAMBDA_ENDPOINT="http://localhost:8081"
ENV_DEV_HLAMBDA_ADMIN_SECRET="demo"

Any hlambda CLI command can now be excuted for different environment, example

$ hl server logs --env dev

$ hl metadata apply --env dev

why is this useful? You can commit the code without commiting secrets to the version control system. And you can have repository containing your metadata and multiple deployments configurations with URL and secrets saved in CI/CD pipeline as different env variables.

to add custom_name environemnt use

$ hl env add custom_name

to delete environment named "staging"

$ hl env delete staging

this will remove the whole environment folder.