• Stars
    star
    485
  • Rank 90,698 (Top 2 %)
  • Language
    Go
  • License
    MIT License
  • Created over 4 years ago
  • Updated 5 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

An opinionated production-ready SQL-/Swagger-first RESTful JSON API written in Go, highly integrated with VSCode DevContainers by allaboutapps.

go-starter

go-starter is an opinionated production-ready RESTful JSON backend template written in Go, highly integrated with VSCode DevContainers by allaboutapps.

License: MIT Build and Test codecov Go Report Card Swagger Validator GitHub contributors Mentioned in Awesome Go

go starter overview

Demo: https://go-starter.allaboutapps.at FAQ: https://github.com/allaboutapps/go-starter/wiki/FAQ

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).

Usage

Please find more detailed information regarding the history, usage and other whys? of this project in our FAQ.

Demo

A demo go-starter service is deployed at https://go-starter.allaboutapps.at for you to play around with.

Please visit our FAQ to find out more about the limitations of this demo environment.

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

Merge with the go-starter template repository to get future updates

These steps are not necessary if you have a "real" fork.

If your new project is generated from a template project (you have a single commit), you want to run the following command immediately and before applying any changes. Otherwise you won't be able to easily merge upstream go-starter changes into your own repository (see GitHub Template Repositories, Refusing to merge unrelated histories and FAQ: I want to compare or update my project/fork to the latest go-starter master).

make git-merge-go-starter
# Attempting to execute 'git merge --no-commit --no-ff go-starter/master' into your current HEAD.
# Are you sure? [y/N]y
# git merge --no-commit --no-ff --allow-unrelated-histories go-starter/master

git commit -m "Initial merge of unrelated go-starter template history"

Set project module name for your new project

To replace all occurrences of allaboutapps.dev/aw/go-stater (our internal module name of this project) with your desired projects' module name, do the following:

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

# Set a new go project module name.
make set-module-name
# allaboutapps.dev/<GIT_PROJECT>/<GIT_REPO> (internal only)
# github.com/<USER>/<PROJECT>
# e.g. github.com/majodev/my-service

The above command writes your new go module name to tmp/.modulename, go.mod. It actually sets it everywhere in **/* - thus this step is typically only required once. If you need to merge changes from the upstream go-starter later, we may want to run make force-module-name to set your own go module name everywhere again (especially relevant for new files / import paths). See our FAQ for more information about this update flow.

Optionally you may want to move the original README.md and LICENSE away:

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

# Optionally you may want to move our LICENSE and README.md away.
mv README.md README-go-starter.md
mv LICENSE LICENSE-go-starter

# Optionally create a new README.md for your project.
make get-module-name > README.md

Visual Studio Code

If you are new to VSCode Remote - Containers feature, see our FAQ: How does our VSCode setup work?.

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!).

Additional resources

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Please make sure to update tests as appropriate.

Current maintainers

Previous maintainers

License

MIT

More Repositories

1

integresql

IntegreSQL manages isolated PostgreSQL databases for your integration tests.
Go
594
star
2

A3ParallaxScrollView

A UIScrollview subclass with a high performance parallax scrolling effect
Objective-C
254
star
3

A3GridTableView

Fast UIScrollView subclass which presents its cells in a GridView
Objective-C
115
star
4

DataSource

Simplifies the setup of UITableView data sources using type-safe descriptors for cells and sections. Animated diffing built-in.
Swift
74
star
5

A3InAppUpdater

Android Library to minimize the implementation effort for In App Updates and Forced Updates
Kotlin
43
star
6

ios-starter

Cookiecutter and XcodeGen template for our iOS apps.
Swift
40
star
7

Fetch

A resource based network abstraction based on Alamofire.
Swift
30
star
8

integresql-client-go

Client library for interacting with a IntegreSQL server, managing isolated PostgreSQL databases for your integration tests.
Go
18
star
9

A3AndroidTemplate

Template project to improve project start experience for android
Kotlin
14
star
10

cra-template-aaa-typescript

Official all about apps React template.
TypeScript
12
star
11

aaa-backend-stack

Deprecated / Legacy: The opinionated Node.js Backend Framework by allaboutapps
TypeScript
9
star
12

Toolbox

Swift
9
star
13

Logbook

Swift
8
star
14

ios-project-template

(Deprecated) Project template for our iOS apps
Swift
6
star
15

react-starter

allaboutapps web frontend starter template using react and vite
TypeScript
5
star
16

gdpr-android

GDPR Library for android projects
Kotlin
5
star
17

allaboutapps.github.io

our developer blog
HTML
4
star
18

android-hiring

aaa Projekt fรผr Bewerber - Team Android
Java
2
star
19

A3Utilities

Android utlitity classes
Java
2
star
20

gdpr-ios

A GDPR framework for iOS
Swift
2
star
21

aws4

Attach and extract signed information to / from URIs via Amazon's AWS Signature Version 4
Go
2
star
22

backup-ns

Application-aware k8s CSI snapshots
Go
1
star
23

A3Dooropener

Java
1
star
24

spm-collection

All our Swift packages in one neat collection
1
star
25

ReactiveForm

Swift
1
star
26

CarouselDemo

Kotlin
1
star
27

A3RecyclerViewDecorations

Decorations for android recyclerviews
Java
1
star
28

A3WebView

Wrapper around WebView
Java
1
star
29

next-starter

An opinionated NextJS starter project with storybook, vitest, mui, tailwind integration. Typesafe i18n included. Dockerfile provided for easy deployment. Tailored for quick scaffolding of projects @ allaboutapps.
TypeScript
1
star