Awesome
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
- Visit
http://localhost:4500
- 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