diff --git a/README.md b/README.md index 9bad2ec..c6f3e38 100644 --- a/README.md +++ b/README.md @@ -1,260 +1,8 @@ -

Go Web Template

+

HomeBox

- - - - - + +

-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](#template-features) - - [General](#general) - - [Mailer](#mailer) - - [Admin / Superuser Management](#admin--superuser-management) - - [Admin](#admin) - - [Self Service](#self-service) - - [Logging](#logging) - - [App Router](#app-router) - - [Web Server](#web-server) - - [Database](#database) - - [Application Configuration](#application-configuration) -- [Management CLI](#management-cli) - - [Docker Setup](#docker-setup) -- [Makefile](#makefile) -- [How To Use: Application API](#how-to-use-application-api) - - [Package Structure (Backend)](#package-structure-backend) - - [app](#app) - - [internal](#internal) - - [pkgs](#pkgs) - - [ent](#ent) - - [Configuring The API](#configuring-the-api) -- [How To Use: Application CLI](#how-to-use-application-cli) - - [Manage Users](#manage-users) - - [List Users](#list-users) - - [Create User](#create-user) - - [Delete User](#delete-user) - -## Template Features - -### General - -- [ ] Test Coverage (WIP) -- [ ] End to End Testing Framework - - [x] Build with TS for ready to go frontend client - - [x] Github CI for end to end testing - - [ ] Basic route tests for end to end testing - - [x] User Auth - - [ ] Admin User Services - - [x] Base API Route -- [x] Basic Backend CI/CD Workflow - - [x] Lint - - [x] Test w/ Coverage - - [x] Build CLI and API -- [ ] Frontend Client - - [ ] Autogenerated types - - [ ] All API Routes (w/ Auth) - -### Mailer - -- [ ] Mailer builder for easy email sending -- [x] Starter email templates - - [x] 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 - -- [x] Logging -- [x] File Logging + STDOUT -- [x] Request Logging (sugar in development structured in prod) -- [x] Dependency Free -- [x] Basic Structured Logging - -### App Router - -- [x] Built on Chi Router -- [x] Basic Middleware Stack - - [x] Logging/Structured Logging - - [x] RealIP - - [x] RequestID - - [x] Strip Trailing Slash - - [x] Panic Recovery - - [x] Timeout - - [x] User Auth - - [ ] Admin Auth -- [x] Auto log registered routes for easy debugging - -### Web Server - -- [x] Router agnostic -- [x] Background Tasks -- [ ] Limited Worker Pool -- [x] Graceful shutdown - - [x] Finish HTTP requests with timeout - - [x] Finish background tasks (no timeout) -- [x] Response Helpers - - [x] Error response builder - - [x] Utility responses - - [x] Wrapper class for uniform responses - -### Database - -- [x] [Ent for Database](https://entgo.io/) - -### Application Configuration - -- [x] Yaml/CLI/ENV Configuration - -
- CLI Args - -``` -Usage: api [options] [arguments] - -OPTIONS - --mode/$API_MODE (default: development) - --web-port/$API_WEB_PORT (default: 3000) - --web-host/$API_WEB_HOST (default: 127.0.0.1) - --database-driver/$API_DATABASE_DRIVER (default: sqlite3) - --database-sqlite-url/$API_DATABASE_SQLITE_URL (default: file:ent?mode=memory&cache=shared&_fk=1) - --database-postgres-url/$API_DATABASE_POSTGRES_URL - --log-level/$API_LOG_LEVEL (default: debug) - --log-file/$API_LOG_FILE - --mailer-host/$API_MAILER_HOST - --mailer-port/$API_MAILER_PORT - --mailer-username/$API_MAILER_USERNAME - --mailer-password/$API_MAILER_PASSWORD - --mailer-from/$API_MAILER_FROM - --seed-enabled/$API_SEED_ENABLED (default: false) - --seed-users/$API_SEED_USERS ,[value...] - --help/-h - display this help message -``` - -
- -
- YAML Config - -```yaml -# 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: example@email.com -``` - -
- -## Management CLI - -- [ ] CLI Interface (Partial) - -### Docker Setup - -- [x] Build and Run API -- [x] 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](https://entgo.io/docs/getting-started) - -### Configuring The API - -See the [Application Configuration](#application-configuration) section for more information. - -## How To Use: Application CLI - -### Manage Users - -#### List Users - -```bash -go run ./app/cli/*.go users list -``` - -#### Create User - -**Development** - -```bash -go run ./app/cli/*.go users add --name=hay-kot --password=password --email=hay-kot@pm.me --is-super -``` - -**Docker** - -```bash -manage users add --name=hay-kot --password=password --email=hay-kot@pm.me -``` - -#### Delete User - -**Development** - -```bash -go run ./app/cli/*.go users delete --id=2 -``` - -**Docker** - -```bash -manage users delete --id=2 -```