Skip to content

๐Ÿ“” 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:

๐Ÿ’ป 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 -o docker-compose.yaml
version: '3.6'
    image: postgres:12
    restart: always
    - hasura_db_data:/var/lib/postgresql/data
      POSTGRES_PASSWORD: postgrespassword
    image: hasura/graphql-engine:v2.3.0-beta.1
    - "8080:8080"
    - "postgres"
    restart: always
      HASURA_GRAPHQL_METADATA_DATABASE_URL: "postgres://postgres:postgrespassword@postgres:5432/postgres"
      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"
    image: hlambda/hlambda-core:latest
      HASURA_GRAPHQL_API_URL: "http://graphql-engine:8080"
      - "8081:1331"
    restart: always
      - hlambda_metadata:/usr/src/app/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 version

$ 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
If you want to check your new API in browser just run:

$ hlambda console

Happy hacking!

๐ŸŽŠ Bonus

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

$ hlambda r g demo
is equivalent to
$ 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
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


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.

Back to top