README.md

Description

This project aims to create an example go/golang web-server. The go-example-webserver/docs directory includes the explanation of the application being built (the docs will have a broader scope than the actual code at the point you're reading this probably). Any feedback is welcome since this is a public project.

Building and running the project

The project is integrated with docker, then running the following commands after setting up a .env file at go-example-webserver/.env, should be enough (there is an example env file in the root directory):

docker-compose build
docker-compose --env-file ./.env up
docker-compose --env-file ./.env up -d # if you want to run the containers in the background

Functional tests and Manual tests

To run the functional tests written in python, or any manual tests, we have to set up the DB, in order to do that, execute the following goose command:

docker-compose run webserver sh bin/goose_apply_migrations.sh ${POSTGRES_USERNAME} ${POSTGRES_PASSWORD}

And then just run:

docker-compose run python_tests pytest

Go Unit tests

To run the unit tests:

docker-compose run go_builder sh bin/go_test.sh

This will generate a coverage report at ./app/src/report/coverage.html.

Go linting

We have some different commands to run Go linters, run the following commands:

docker-compose run go_builder sh bin/go_fmt.sh
docker-compose run go_builder sh bin/go_vet.sh
docker-compose run go_builder sh bin/staticcheck.sh

Python linting

To run pylint use the following command:

docker-compose run python_tests sh bin/pylint.sh

Goose and PostgreSQL DB Info

To connect to the DataBase, use the following command (replace ${MICROSERVICE} by the affected microservice):

docker-compose run postgres_${MICROSERVICE} psql --host=postgres_${MICROSERVICE} --username=${POSTGRES_USERNAME} --dbname=${POSTGRES_DB_NAME}

To create a new DB migration use the following command:

docker-compose run ${MICROSERVICE} sh bin/goose_new_migration.sh ${MIGRATION_NAME}

To apply the db_migrations use the following command:

docker-compose run ${MICROSERVICE} sh bin/goose_apply_migrations.sh ${POSTGRES_CONTAINER} ${POSTGRES_USERNAME} ${POSTGRES_PASSWORD} ${POSTGRES_DB_NAME}

To unapply the db_migrations use the following command:

docker-compose run ${MICROSERVICE} sh bin/goose_downgrade_migration.sh ${POSTGRES_CONTAINER} ${POSTGRES_USERNAME} ${POSTGRES_PASSWORD} ${POSTGRES_DB_NAME}

Adding or updating Go dependencies

To add new go dependencies we just have to use the following commands inside the app directory. This can be done through your local environment as long as you have go installed.

go get ${DEPENDENCY}@${VERSION}
go mod tidy

If you are adding an executable go dependency, add it to the tools.go file and follow the instructions there (basically the same instructions above).

Adding or updating Python dependencies

So far I've been adding these manually to the test/requirements.txt file. After that, we need to re-build the python container.

Updating Protos

Update the app/bin/generate_protos.sh and test/bin/generate_protos.sh and then execute the following commands:

docker-compose run go_builder sh bin/generate_protos.sh
docker-compose build python_tests
docker-compose run python_tests sh bin/generate_protos.sh

Updating Webserver endpoints

In order to modify the webserver endpoints, we have to follow some guidelines related to the go-swagger spec generation:

• To generate the go swagger files:

docker-compose run go_builder swagger generate spec -o ./swagger/swagger.yaml
docker-compose run go_builder swagger generate spec -o ./swagger/swagger.json

Check the Swagger docs (HTML)

Going to the localhost/swagger URL in a browser (after running the project) should be enough!

Call gRPC endpoints manually

Execute the following command:

docker-compose run go_builder grpcurl -plaintext -d '${REQUEST_BODY}' ${MICROSERVICE}:8080 go_webserver.${MICROSERVICE}.${SERVICE}/${RPC}

Call Webserver endpoints manually

Will refine this section soon but the webserver endpoints should be accessible via postman, curl or any other http client by calling the localhost/api URL.

Changes and Pull Requests

Every change has to be made via a Pull Request, and CircleCI checks are needed. Even for the repo administrators.

Github Releases

To understand how Github releases work for this repository, this documentation should be useful: https://github.com/go-modules-by-example/index/blob/master/009_submodules/README.md. This section will probably change once a Vue js UI is added.

Dependabot

This repo uses Dependabot to keep its Go dependencies up to date. The config was created following this blog article: https://github.blog/2020-06-01-keep-all-your-packages-up-to-date-with-dependabot/ And the github docs: https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuring-dependabot-version-updates