Skip to content

Latest commit

 

History

History
139 lines (96 loc) · 6.41 KB

README.md

File metadata and controls

139 lines (96 loc) · 6.41 KB
Raw

Golang Rest API example

trip-planner is an opinionated production-ready RESTful JSON backend template written in Go, highly integrated with VSCode DevContainers.

Table of Contents

Features

  • Full local golang service development environment using Docker Compose and VSCode devcontainers that just works with Linux, MacOS and Windows.
  • Adheres to the project layout defined in golang-standard/project-layout.
  • Provides database migration (sql-migrate) and models generation (SQLBoiler) workflows for PostgreSQL databases.
  • Integrates IntegreSQL for fast, concurrent and isolated integration testing with real PostgreSQL databases.
  • Auto-installs our recommended VSCode extensions for golang development.
  • Integrates go-swagger for compile-time generation of swagger.yml, structs and request/response validation functions.
  • Integrates MailHog for easy SMTP-based email testing.
  • Integrates SwaggerUI for live-previewing your Swagger v2 schema.
  • Integrates pgFormatter and vscode-pgFormatter for SQL formatting.
  • Comes with fully implemented auth package, an OAuth2 RESTful JSON API ready to be extended according to your requirements.
  • Implements OAuth 2.0 Bearer Tokens and password authentication using argon2id hashes.
  • Comes with a tested mock and FCM provider for sending push notifications and storing push tokens.
  • CLI layer provided by spf13/cobra. It's exceptionally easy to add additional sub-commands via cobra-cli.
  • Comes with an initial PostgreSQL database structure (see /migrations), covering:
    • auth tokens (access-, refresh-, password-reset-tokens),
    • a generic auth-related user model
    • an app-specific bare-bones app_user_profile model,
    • push notification tokens and
    • a health check sequence (for performing writeable checks).
  • API endpoints and CLI for liveness (/-/healthy) and readiness (/-/ready) probes
  • Parallel jobs optimized Makefile and various convenience scripts (see all targets and its description via make help). A full rebuild only takes seconds.
  • Multi-staged Dockerfile (development -> builder -> app).

Requirements

Requires the following local setup for development:

This project makes use of the Remote - Containers extension provided by Visual Studio Code. A local installation of the Go tool-chain is no longer required when using this setup.

Please refer to the official installation guide how this works for your host OS and head to our FAQ: How does our VSCode setup work? if you encounter issues.

Quickstart

Create a new git repository through the GitHub template repository feature (use this template). You will then start with a single initial commit in your own repository.

# Clone your new repository, cd into it, then easily start the docker-compose dev environment through our helper
./docker-helper.sh --up

You should be inside the 'service' docker container with a bash shell.

development@94242c61cf2b:/app$ # inside your container...

# Shortcut for make init, make build, make info and make test
make all

# Print all available make targets
make help

Visual Studio Code

Run CMD+SHIFT+P Go: Install/Update Tools after attaching to the container with VSCode to auto-install all golang related vscode extensions.

Building and testing

Other useful commands while developing your service:

development@94242c61cf2b:/app$ # inside your container...

# Print all available make targets
make help

# Shortcut for make init, make build, make info and make test
make all

# Init install/cache dependencies and install tools to bin
make init

# Rebuild only after changes to files (generate, format, build, lint)
make

# Execute all tests
make test

Running

To run the service locally you may:

development@94242c61cf2b:/app$ # inside your development container...

# First ensure you have a fresh `app` executable available
make build

# Check if all requirements for becoming are met (db is available, mnt path is writeable)
app probe readiness -v

# Migrate up the database
app db migrate

# Seed the database (if you have any fixtures defined in `/internal/data/fixtures.go`)
app db seed

# Start the locally-built server
app server

# Now available at http://127.0.0.1:8080

# You may also run all the above commands in a single command
app server --probe --migrate --seed # or `app server -pms`

Uninstall

Simply run ./docker-helper --destroy in your working directory (on your host machine) to wipe all docker related traces of this project (and its volumes!).

License

MIT