DEV.md

Development

To start a development server it requires the following local tools:

• Golang 1.22+
• Docker
• Clojure / Java
• git
• Postgres Server (remote or local)
• node / npm

Start a postgres server

Start and bootstrap a postgres server in background

make run-dev-postgres

If you already have a postgres server, you don't need to execute this step.

Start the server

The configuration file to run the development server is located at .env.

# edit .env file with your favorite editor
cp .env.sample .env

The sample configuration file doesn't have a default identity provider. Make sure to configure one to be able to run this project.

make run-dev

Webapp Setup

To build the webapp into the gateway

WEBAPP_BUILD=1 make run-dev

Build Dev Client

By default versioned clients are builded to strict connect via TLS. In order to build a client that permits connecting to remote hosts without TLS, execute the instruction below:

# generate binary at $HOME/.hoop/bin/hoop
make build-dev-client

Append $HOME/.hoop/bin to your $PATH in your profile to find commands when typing in your shell

Swagger / OpenAPI

This project uses swag to generate the api documentation. Make sure to generate it every time a change is made in the API:

make generate-openapi-docs

The gateway will expose the the openapi spec at /api/openapiv2.json and /api/openapiv3.json. Use your favorite openapi ui to view the documentation:

• https://swagger.io/tools/swagger-ui/
• https://redocly.github.io/redoc/

Postgrest

This project uses postgrest as an interface to Postgres, it allows creating api's based on tables schema and permissions. The bootstrap process performs all the necessary setup to make the postgrest fully functional, it consists in three steps:

• Perform the migration process using the go-migrate library
• Provisioning the roles and permissions required for postgrest to work properly. See authentication.
• Running the postgrest process in background

Running Migrations

Install the golang migrate cli in your local machine

1. In the root folder of the project, run the following command:

migrate create -ext sql -dir rootfs/app/migrations -seq my_new_change

2. Add the up and down migrations
3. Start the gateway and it will automatically apply all migrations
4. Test reverting the migration

migrate -database 'postgres://hoopdevuser:[email protected]:5449/hoopdevdb?sslmode=disable' -path rootfs/app/migrations/ down 1

In case of adding new views, make sure to add the proper permissions in the bootstrap process of postgrest

Migration Best Practices

• https://github.com/golang-migrate/migrate/blob/master/MIGRATIONS.md