mirrors/homebox
1
0
Fork 1
mirror of https://github.com/hay-kot/homebox.git synced 2024-12-19 05:26:31 +00:00
Code Issues Projects Releases Packages Wiki Activity

update README

Browse source
This commit is contained in:
Hayden 2022-09-03 10:44:49 -08:00
parent 10f5da4727
commit 5052a91e12
1 changed files with 3 additions and 255 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

258
README.md
View file

@ -1,260 +1,8 @@
<h1 align="center"> Go Web Template</h1>
<h1 align="center"> HomeBox </h1>
<p align="center" style="width: 100%">
<a href="https://github.com/hay-kot/content/actions/workflows/go.yaml">
<img src="https://github.com/hay-kot/content/actions/workflows/go.yaml/badge.svg?branch=master"/>
</a>
<a href="https://codecov.io/gh/hay-kot/content">
<img src="https://codecov.io/gh/hay-kot/content/branch/master/graph/badge.svg?token=8EN4BQLIUS"/>
<a href="https://github.com/hay-kot/homebox/actions/workflows/go.yaml">
<img src="https://github.com/hay-kot/homebox/actions/workflows/go.yaml/badge.svg?branch=master"/>
</a>
</p>
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
<details>
<summary> CLI Args </summary>
```
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
```
</details>
<details>
<summary> YAML Config </summary>
```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
```
</details>
## 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
```