Echo REST API boilerplate

A Golang restful API boilerplate based on Echo framework v4. Includes tools for module generation, db migration, authorization, authentication and more. Any feedback and pull requests are welcome and highly appreciated. Feel free to open issues just for comments and discussions.

• Echo REST API boilerplate
  • Overview
  • Features
  • Running the project
  • Environment variables
  • Commands
  • Folder structure
  • Open source refs
  • Contributing
  • TODOs

HOW TO USE THIS TEMPLATE

DO NOT FORK this is meant to be used from Use this template feature.

1. Click on Use this template
2. Give a name to your project
   (e.g. my_awesome_project recommendation is to use all lowercase and underscores separation for repo names.)
3. Wait until the first run of CI finishes
   (Github Actions will process the template and commit to your new repo)
4. Then clone your new project and happy coding!

NOTE: WAIT until first CI run on github actions before cloning your new project.

Overview

Features

• User Auth functionality (Signup, Login, Forgot Password, Reset Password, 2FA) using Ory/Kratos.
• REST API using labstack/echo.
• DB Migration using golang-migrate/migrate.
• Modular structure.
• Configs via environmental variables.
• Unit tests.
• Dependency injection using uber-go/dig.
• Role based access control using Open Policy Agent.
• Module generation, quickly create model, usecase, api handler.
• CLI support. try: go run ./tools/mod/ gen using spf13/cobra.
• Generate API docs using swaggo. Try: make docs.

Running the project

• Make sure you have docker installed.
• Copy .env.example to .env.docker
• Add a new line 127.0.0.1 echo-rest.local to /etc/hosts file.
• Run docker compose up -d.
• Go to echo-rest.local:8088 to verify if the API server works.
• Go to echo-rest.local:4455 to verify if the Kratos works.

Environment variables

By default, when you run application with make run-api command, it will look at $HOME/.env for exporting environment variabels. Setting your config as Environment Variables is recommended as by 12-Factor App.

Variables Defined in the project

Name	Type	Description	Example value
DATABASE_URL	string	Data source URL for main DB	postgres://world:hello@postgres/echo_rest_api
KRATOS_API_ENDPOINT	string	Public endpoint of Kratos	http://kratos:4433/
KRATOS_WEBHOOK_API_KEY	string	Api key for Kratos integration	very-very-very-secure-api-key
PORT	integer	Http port (accepts also port number only for heroku compability)	8088
AUTO_MIGRATE	boolean	Enable run migration every time the application starts	true
ENV	string	Environment name	development
REDIS_URL	string	Optional	redis://redis:6379

Commands

Command	Description
make run-api	Start REST API application
make build-api	Build application binary
make setup	Run commands to setup development env
make run-db	Run DB docker container on local
go run ./tools/mod/ gen	Generate module component codes.
make migration-create [migration_name]	Create migration files. migration_name should be snake case
make git-hooks	Setup git hooks
make routes	Generate routes file for authorization
make docs	Generate API docs

Folder structure

.
├── 3rd-parties         # Thirdparty configs
├── cmd
│   └── api             # Main package of API service
├── config              # Application configs struct
│   ...        
├── docs                # Content documentation and PlantUML for charts and diagrams
├── domains
├── infrastructure
├── migrations
│   └── sql             # Migration files
├── modules
│   ├── core            # Core module, includes apis: users, orgs
│   ├── projects        # Demo module generation
│   └── shared          # To store common usecases and domains which shared between modules
├── out                 # Output folder of PlantUML
├── pkg
│   ├── authz           # Contents Rego rule files for RBAC
│   ├── constants
│   ├── cue             # Contents cue files for data validation
│   ...
│   └── utils           # Contents helper functions
├── tests
└── tools
   ├── modtool         # Module generation
   ├── routes          # Generate routes file for Authorization
   └── scripts         # Some helpful bash commands

Open source refs

• https://www.ory.sh/docs/kratos/self-service
• https://cuelang.org/docs/about/
• https://www.openpolicyagent.org/docs/latest/
• https://echo.labstack.com/guide/

Contributing

Please open issues if you want the template to add some features that is not in todos.

Create a PR with relevant information if you want to contribute in this template.

TODOs

• Update docker compose for ory/kratos.
• Update README.md.
• Update API docs.
• Write more tests.
• Add support Heroku.