README.md

PNGR Stack 🏓

Dockerized (postgres + nginx + golang + react) starter kit

Only implements users, sessions, password_resets, and a toy post type to demonstrate basic CRUD. PNGR is not a CMS.

Features and Stack

• Hot-reload, front and back, including a test-runner for golang changes

Back-end

• golang-migrate already configured for easy migrations
• sqlc for auto-generated sql bindings
• gomock for auto-generated mocks (also rigged with hot-reload!)
• pgx as a top tier db driver
• golang-jwt cookies with automatic refresh: ready for horizontal scaling
• Simple default middleware for CORS, CSRF, cookie parsing, etc.
• httprouter for simple back-end routing

Front-end

• Vite dev server
• Vitest integration
• React Router for front-end routing
• React Context for global user state
• Functional-style typescript components throughout, including some helpful custom hooks to simplify building forms
• Semantic UI React for component library with functional theme variables and hot-reload

Other goodies

• "Server-side rendering" with a prerender sidecar container
• A golang worker container stubbed out for async (non-API) tasks

Feature development is up to you!

Requirements

Install docker && docker-compose

Quick Start

# clone the repo
git clone https://github.com/karlkeefer/pngr.git my_project_name

# copy the .env template for your local version
cp .env.example .env

# build and start the containers
docker-compose up

1. Visit http://localhost:4500
2. Make changes to go, sql, or react code, and enjoy hot-reload goodness!

Run client-side test watcher

docker-compose exec react npm run test

Database Helpers

Migrations

Migrations are created and run using simple wrappers around go-migrate.

# create files for a new migration
postgres/new my_migration_name

# execute any new migrations (this is also run automatically the container is created)
postgres/migrate up

# go down 1 migration
postgres/migrate down 1

# goto a migration by index
postgres/migrate goto 3

Open a psql client

# remember to use \q to exit
postgres/psql

Rebuild everything, including database(!), from scratch

Maybe your postgres went sideways from a wonky migration and it's easier to restart from scratch.

docker-compose down -v && docker-compose up --build --force-recreate

Run in Production

Warning: Run in production at your own risk!

docker-compose.prod.yml is designed for a setup where postgresql is not dockerized.

Don't forget to copy .env.example -> .env and setup your secrets/passwords for the new environment! At minimum, you'll need to change ENV, APP_ROOT, and TOKEN_SECRET!

# build production images, and run them in a detached state
docker-compose -f docker-compose.prod-build.yml up --build -d

Note: using your production server as your build server is a bad idea, so you should consider using a registry...

Using CI

You can modify the github action to push built containers to a container registry. The containers are tagged with the commit SHA by default.

You will also need to update docker-compose.prod.yml to point to your container registry.

# pull containers from a registry using a tag, then run them in a detached state
SHA=2c25e862e0f36e0fc17c1703e4f319f0d9d04520 docker-compose -f docker-compose.prod.yml up -d