Surreal-Fiber Boilerplate
A REST API boilerplate for the Fiber web framework using SurrealDB.
Table of Contents:
Features
Configuration
This boilerplate leverages Viper to manage configurations. This allows you to use environment variables, JSON, TOML, YAML, HCL, and Java properties config files.
Routing
An example of how routing is done can be found in the /routes directory. Whilst the original boilerplate contained web routes, this version removed those and focuses entirely on API routes. This is done to keep the boilerplate as simple as possible.
Controllers
An example of how controllers are done can be found in the /app/controllers directory. This is where you can add your own controllers.
Database
This boilerplate uses SurrealDB as its database. This is a very fast and lightweight database that is perfect for projects that want to be as efficient as possible. It is also very easy to use and has a very simple API.
Docker
Included in the repository is a Dockerfile that outputs a highly efficient container using scratch as the base image. This is a very small image that only contains the compiled binary.
Live Reloading (Air)
This boilerplate uses Air for live-reloading. Air watches files for changes, and restarts the build & run process when a change is detected.
Structured Logger
Leveraging Zap, this boilerplate uses a structured logger to log messages. This allows you to easily filter and search for messages in your logs.
It can be found in /app/utils/structured_logger.go.
This logger trades performance for API usability. If you want to use a logger that is more performant, you can use the default logger that is included in Fiber, or use Zap directly.
Configuration
Configurations are in a single file called .env. You can copy the .env.full and change it to your needs.
A blank .env file is included in the repository, to prevent errors when building the Docker container.
The file is copied into the Docker container on build and is loaded by Viper on application startup.
Keep in mind if configurations are not set, they default to Fiber's default settings which can be found here.
Database
We use SurrealDB for its performance. Please check out their documentation here.
To get started with SurrealDB, you need to follow these steps:
- Install SurrealDB
- Start SurrealDB with debug configuration:
Further instructions about startup can be found here.
surreal start --log debug --user root --pass root memory
- Make sure the configuration in your
.envfile or inconfig/config.gomatches the configuration you used to start SurrealDB. - Start the project.
Docker
Included in the repository is a Dockerfile that outputs a highly efficient container using scratch as the base image. This is a very small image that only contains the compiled binary.
Do note that this can cause issues in more complex applications, notably if the net module is used. See this StackOverflow answer.
To build the Docker image, use the following command:
docker build -t fiber-boilerplate .To run the Docker image, use the following command:
docker run -p 8080:8080 fiber-boilerplateLive Reloading (Air)
Example configuration files for Air have also been included. This allows you to live reload your Go application when you change a model, view or controller which is very useful when developing your application.
To run Air, use the following commands. Also, check out Air its documentation about running the air command.
# Windows
air -c .air.windows.conf
# Linux / MacOS
air -c .air.linux.conf
# or
./start.linux.shAcknowledgements
This template was forked from Thomas van Vugt's original repository and adapted to a REST API and SurrealDB centric development pipeline.
Thanks to Fiber for their amazing web framework.
Special thanks to SurrealDB for their amazing database.
License
All code and files within this repository, with the exception of the Fiber Logo and the SurrealDB Logo are licensed under the MIT license.
The Fiber Logo and SurrealDB Logo are owned by their respective owners and may be licensed differently to this repository.