Go Web Template

This Go Web Template is a simple starter template for a Go web application. It includes a web server API, as well as a starter CLI to manage the web server/database inside the container. It should be noted that while while use of the standard library is a high priority, this template does make use of multiple external packages. It does however abide by the standard http handler pattern.

• Template Features
  • General
  • Mailer
  • Admin / Superuser Management
    • Admin
    • Self Service
  • Logging
  • App Router
  • Web Server
  • Database
  • Application Configuration
• Management CLI
  • Docker Setup
• Makefile
• How To Use: Application API
  • Package Structure (Backend)
    • app
    • internal
    • pkgs
    • ent
  • Configuring The API
• How To Use: Application CLI
  • Manage Users
    • List Users
    • Create User
    • Delete User

Template Features

General

• Test Coverage (WIP)
• End to End Testing Framework
  • Build with TS for ready to go frontend client
  • Github CI for end to end testing
  • Basic route tests for end to end testing
    • User Auth
    • Admin User Services
    • Base API Route
• Basic Backend CI/CD Workflow
  • Lint
  • Test w/ Coverage
  • Build CLI and API
• Frontend Client
  • Autogenerated types
  • All API Routes (w/ Auth)

Mailer

• Mailer builder for easy email sending
• Starter email templates
  • Activate Account
  • Password Reset
• Bulk Messages

Admin / Superuser Management

Admin

• CRUD Operations for Users

Self Service

• User sign-up
• Require Activation by Email
• Stateful Token Auth
• Login/Logout
• Password Reset by Email

Logging

• Logging
• File Logging + STDOUT
• Request Logging (sugar in development structured in prod)
• Dependency Free
• Basic Structured Logging

App Router

• Built on Chi Router
• Basic Middleware Stack
  • Logging/Structured Logging
  • RealIP
  • RequestID
  • Strip Trailing Slash
  • Panic Recovery
  • Timeout
  • User Auth
  • Admin Auth
• Auto log registered routes for easy debugging

Web Server

• Router agnostic
• Background Tasks
• Limited Worker Pool
• Graceful shutdown
  • Finish HTTP requests with timeout
  • Finish background tasks (no timeout)
• Response Helpers
  • Error response builder
  • Utility responses
  • Wrapper class for uniform responses

Database

• Ent for Database

Application Configuration

• Yaml/CLI/ENV Configuration

CLI Args

Usage: api [options] [arguments]

OPTIONS
  --mode/$API_MODE                                    <string>            (default: development)
  --web-port/$API_WEB_PORT                            <string>            (default: 3000)
  --web-host/$API_WEB_HOST                            <string>            (default: 127.0.0.1)
  --database-driver/$API_DATABASE_DRIVER              <string>            (default: sqlite3)
  --database-sqlite-url/$API_DATABASE_SQLITE_URL      <string>            (default: file:ent?mode=memory&cache=shared&_fk=1)
  --database-postgres-url/$API_DATABASE_POSTGRES_URL  <string>
  --log-level/$API_LOG_LEVEL                          <string>            (default: debug)
  --log-file/$API_LOG_FILE                            <string>
  --mailer-host/$API_MAILER_HOST                      <string>
  --mailer-port/$API_MAILER_PORT                      <int>
  --mailer-username/$API_MAILER_USERNAME              <string>
  --mailer-password/$API_MAILER_PASSWORD              <string>
  --mailer-from/$API_MAILER_FROM                      <string>
  --seed-enabled/$API_SEED_ENABLED                    <bool>              (default: false)
  --seed-users/$API_SEED_USERS                        <value>,[value...]
  --help/-h
  display this help message

YAML Config

# config.yml
---
mode: development
web:
  port: 3915
  host: 127.0.0.1
database:
  driver: sqlite3
  sqlite-url: ./ent.db?_fk=1
logger:
  level: debug
  file: api.log
mailer:
  host: smtp.example.com
  port: 465
  username:
  password:
  from: [email protected]

Management CLI

• CLI Interface (Partial)

Docker Setup

• Build and Run API
• Build and Setup CLI in path

Makefile

• Build and Run API: make api
• Build Production Image make prod
• Build CLI make cli
• Test make test
• Coverage make coverage

How To Use: Application API

Package Structure (Backend)

app

The App folder contains the main modules packages/applications that utilize the other packages. These are the applications that are compiled and shipped with the docker-image.

internal

Internal packages are used to provide the core functionality of the application that need to be shared across Applications but are still tightly coupled to other packages or applications. These can often be bridges from the pkgs folder to the app folder to provide a common interface.

pkgs

The packages directory contains packages that are considered drop-in and are not tightly coupled to the application. These packages should provide a simple and easily describable feature. For example. The hasher package provides a Password Hashing function and checker and can easily be used in this application or any other.

A good rule to follow is, if you can copy the code from one package to a completely. different project with no-modifications, it belongs here.

ent

As an exception to the above, this project adhears to the convention set by Ent we use a ent folder to contain the database schema. If you'd like to replace the Ent package with an alternative, you can review the repository layer in the internal folder.

Checkout the Entgo.io Getting Started Page

Configuring The API

See the Application Configuration section for more information.

How To Use: Application CLI

Manage Users

List Users

go run ./app/cli/*.go users list

Create User

Development

go run ./app/cli/*.go users add --name=hay-kot --password=password [email protected] --is-super

Docker

manage users add --name=hay-kot --password=password [email protected]

Delete User

Development

go run ./app/cli/*.go users delete --id=2

Docker

manage users delete --id=2