brain

README

🧠 Brain

About

Brain is a GraphQL monolithic service made with Go that serves as back-end for the main web application of Associació Valenciana pel Transport Públic (Valencian Association for Public Transport), a non-profit organization whose goal is to achieve the public transport that the Valencian society deserves.

Directory structure

The project follows the de facto standard Go project layout with the following additions:

• helm, .dockerignore, .env.example, docker-compose.yml, Dockerfile and Makefile contain the configuration and manifests that define the development and runtime environments with Docker and Docker Compose.
• .github holds the GitHub Actions CI/CD pipelines.

License

This software is distributed under the GNU General Public License v3.0. Please read the software license for more information on the availability and distribution.

Getting started

This project comes with a containerized environment that has everything necessary to develop on any platform.

TL;TR

make

Requirements

Before starting using the project, make sure that Docker Desktop (or, separately, Docker and Docker Compose) are installed on the machine.

It is necessary to install the latest versions before continuing. You may follow the previous links to read the installation instructions.

Initializing

First, initialize the project and run the environment.

make

Then, download third-party dependencies and run the database migrations.

make deps

You may stop the environment by running the following command.

make down

Usage

You can run commands inside the virtual environment by running a shell in the container (make shell).

Running the development server

Run the following command to start the development server.

make run

Note that Git is not available in the container, so you should use it from the host machine. It is strongly recommended to use a desktop client like Fork or GitKraken.

Running tests

To run all automated tests, use the following command.

make test

Debugging

It is possible to debug the software with Delve. To run the application in debug mode, run the command below.

make debug

For more advanced scenarios, such as debugging tests, you may open a shell in the container and use the Delve CLI directly.

make shell
dlv test --listen=:8001 --headless --api-version=2 ./internal/api/resolvers/resolvers_test

Deployment

The deployment process is automated with GitHub Actions. When changes are incorporated into production (main branch) or staging (develop branch), an automatic deployment is made to the corresponding environment.

Troubleshooting

There are several common problems that can be easily solved. Here are their causes and solutions.

Docker

The Docker environment should work properly. Otherwise, it is possible to rebuild it by running the following commands.

docker compose down
docker compose build --no-cache main

To start from scratch, you can remove all containers, images and volumes of your computer by running the following commands.

Note that all system containers, images and volumes will be deleted, not only those related to this project.

docker compose down
docker rm $(docker ps -a -q)
docker rmi $(docker images -q)
docker volume rm $(docker volume ls -f dangling=true -q)