trip-planner

README

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

• Next js and Golang example
  • Table of Contents
  • Features
    • Requirements
    • Quickstart
    • Visual Studio Code
    • Building and testing
    • Running
    • Uninstall
  • License

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:

• Docker CE (19.03 or above)
• Docker Compose (1.25 or above)
• VSCode Extension: Remote - Containers (ms-vscode-remote.remote-containers)

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