README
¶
Golastic
Golastic is a web API offering full text search and CRUD operations on a book collection via Elasticsearch.
Table of contents
Getting started
Installation and dependencies
You must be able to run Docker and Docker Compose on your local machine to run this app. Refer to the Get Docker and Install Docker Compose docs for their installation.
Run the project in Docker
The app is fully dockerized. To start all required containers, simply run:
make
# alias to:
# docker-compose --env-file ./.env.docker up --build
That's it! The app is ready to be used. See Test with queries to learn about our available queries.
To shut down the containers, run:
make down
# equivalent to:
# docker-compose down
Run the server locally
Go 1.16 minimum is required due to the use of newer features (notably go:embed).
To start the server locally with Elasticsearch containers in the background, run:
make local
# alias to:
# docker-compose --env-file ./.env.local up --detach elasticsearch kibana && \
# go run cmd/main.go --env-file ./.env.local
Alternatively, if you wish to keep track of elasticsearch containers output:
# Terminal window 1 - run elasticsearch containers
make local-env
# alias to:
# docker-compose --env-file ./.env.local up elasticsearch kibana
# Terminal window 2 - run web server
make local-server
# alias to:
# go run cmd/main.go --env-file ./.env.local
You may also want to populate Elasticsearch index with dummy data. See Populate with dummies for more on this.
Test and lint
Run all tests:
make test
# alias to:
# go test -v -timeout 30s ./...
Run a specific test with t to specify a test and p to specify a package (parameters are independent):
make test t=TestMarshaling p=pkg/golastic
# alias to:
# go test -v -timeout 30s -run TestMarshaling ./pkg/golastic
Run the linter:
We use golangci-lint in our CI. It runs on each push to a branch with an open PR.
make lint
# alias to:
# golangci-lint run
Populate with dummies
You may use a CLI flag to populate Elasticsearch's index on start-up. To use it, simply run:
go run cmd/main.go -p
Only the first run (or any run following an erasure of the Docker volume) requires the use of this flag, as the dummy data will not be overwritten.
Test routes with CURL commands
Refer to the routes specifition for detailed requests queries and responses data. It comes with handy CURL commands to quickly test the routes at runtime.
Architecture
Folder structure
The main functional packages for the project are:
.
├── cmd
├── internal
│ ├── http
│ └── repository
└── pkg
├── golastic
└── ...
internal
The main application code. It defines domain related entities at its root and its child packages are grouped by dependencies (data access and transport).
pkg
Purposeful and reusable library code. It does not import any types from internal and does not rely on it to work. There is no domain logic inside this directory.
cmd
Main application for the project. A main function imports and call code from internal or pkg. It ties all dependencies together and injects runtime variables.
Further documentation
Sub-packages have their own documentation when it is relevant. You may refer to these docs:
Moreover, all types, functions and methods are documented.
Acknowledgement and contributors
This project is part of an school assignement. Our team members are:
- Gregory Albouy
- Thomas Moreira
- Damien Mathieu
Directories