An opinionated production-ready SQL-/Swagger-first RESTful JSON API written in Go, highly integrated with VSCode DevContainers by allaboutapps.
Golang RESTful API Starter 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.
- It 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.
- It 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
- Comes with an initial PostgreSQL database structure (see /migrations), covering:
- auth tokens (access-, refresh-, password-reset-tokens),
- a generic auth-related
- an app-specific bare-bones
- push notification tokens and
- a health check sequence (for performing writeable checks).
- API endpoints and CLI for liveness (
/-/healthy) and readiness (
- Parallel jobs optimized
Makefileand various convenience scripts (see all targets and its description via
make help). A full rebuild only takes seconds.
Go Project Usage
Please find more detailed information regarding the history, usage and other whys? of this project in our FAQ.
A demo go-starter service is deployed at https://go-starter.allaboutapps.at for you to play around with.
Please visit our FAQ to learn more about this demo environment’s limitations.
Requires the following local setup for development:
- Docker CE (19.03 or above)
- Docker Compose (1.25 or above)
- VSCode Extension: Remote – Containers (
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.
[email protected]:/app$ # inside your container... # Shortcut for make init, make build, make info and make test make all # Print all available make targets make help
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 merge upstream go-starter changes into your own repository easily (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"
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:
[email protected]:/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
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
[email protected]:/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
If you are new to VSCode Remote – Containers feature, see our FAQ: How does our VSCode setup work?.
Go: Install/Update Tools after attaching to the container with VSCode to auto-install all golang related vscode extensions.
Other useful commands while developing your service:
[email protected]:/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
To run the service locally you may:
[email protected]:/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`
./docker-helper --destroy in your working directory (on your host machine) to wipe all docker related traces of this project (and its volumes!).
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.