Pagoda

Pagoda: Rapid, easy full-stack web development starter kit in Go

<p align="center"><img alt="Logo" src="https://user-images.githubusercontent.com/552328/147838644-0efac538-a97e-4a46-86a0-41e3abdf9f20.png" height="200px"/></p>

Table of Contents

• Introduction
  • Overview
  • Foundation
    • Backend
    • Frontend
    • Storage
  • Screenshots
• Getting started
  • Dependencies
  • Getting the code
  • Installing tools
  • Create an admin account
  • Start the application
  • Live reloading
• Service container
  • Dependency injection
  • Test dependencies
• Configuration
  • Environment overrides
  • Environments
• Database
  • Auto-migrations
  • Separate test database
• ORM
  • Entity types
  • New entity type
• Sessions
  • Encryption
• Authentication
  • Login / Logout
  • Forgot password
  • Registration
  • Admins
  • Authenticated user
    • Middleware
  • Email verification
• Admin panel
  • Code generation
  • Access
  • Considerations
  • Roadmap
• Routes
  • Custom middleware
  • Handlers
  • Errors
  • Redirects
  • Testing
    • HTTP server
    • Request / Request helpers
    • Goquery
• User interface
  • Why Gomponents?
  • HTMX support
    • Header management
    • Conditional and partial rendering
    • CSRF token
  • CSS
  • Request
    • Title and metatags
    • URL generation
  • Components
  • Layouts
  • Pages
    • Rendering
  • Forms
    • Submission processing
    • Inline validation
    • CSRF
  • Models
  • Icons
  • Node caching
  • Flash messaging
• Pager
• Cache
  • Set data
  • Get data
  • Flush data
  • Flush tags
• Tasks
  • Queues
  • Dispatcher
  • Monitoring tasks and queues
• Cron
• Files
  • Uploads
  • Static files
    • Cache-buster
  • Public files
  • Cache control headers
• Email
• HTTPS
• Logging
• Credits

Introduction

Overview

Pagoda is not a framework but rather a base starter-kit for rapid, easy full-stack web development in Go, aiming to provide much of the functionality you would expect from a complete web framework as well as establishing patterns, procedures and structure for your web application.

Built on a solid foundation of well-established frameworks and modules, Pagoda aims to be a starting point for any web application with the benefit over a mega-framework in that you have full control over all of the code, the ability to easily swap any frameworks or modules in or out, no strict patterns or interfaces to follow, and no fear of lock-in.

While separate JavaScript frontends have surged in popularity, many prefer the reliability, simplicity and speed of a full-stack approach with server-side rendered HTML. Even the popular JS frameworks all have SSR options. This project aims to highlight that Go alone can be powerful and easy to work with as a full-stack solution, and interesting frontend libraries can provide the same modern functionality and behavior without having to write any JS or CSS at all. In fact, you can even avoid writing HTML as well.

Foundation

While many great projects were used to build this, all of which are listed in the credits section, the following provide the foundation of the back and frontend. It's important to note that you are <ins>not required to use any of these</ins>. Swapping any of them out will be relatively easy.

Backend

• Echo: High performance, extensible, minimalist Go web framework.
• Ent: Simple, yet powerful ORM for modeling and querying data.
• Gomponents: HTML components written in pure Go. They render to HTML 5, and make it easy for you to build reusable components.

Frontend

Go server-side rendered HTML combined with the projects below enable you to create slick, modern UIs without writing any JavaScript or CSS.

• HTMX: Access AJAX, CSS Transitions, WebSockets and Server Sent Events directly in HTML, using attributes, so you can build modern user interfaces with the simplicity and power of hypertext.
• Alpine.js: Rugged, minimal tool for composing behavior directly in your markup. Think of it like jQuery for the modern web. Plop in a script tag and get going.
• DaisyUI: The Tailwind CSS plugin you will love! It provides useful component class names to help you write less code and build faster. No JavaScript dependencies.

Storage

• SQLite: A small, fast, self-contained, high-reliability, full-featured, SQL database engine and the most used database engine in the world.

Originally, Postgres and Redis were chosen as defaults but since the aim of this project is rapid, simple development, it was changed to SQLite which now provides the primary data storage as well as persistent, background task queues. For caching, a simple in-memory solution is provided. If you need to use something like Postgres or Redis, swapping those in can be done quickly and easily. For reference, this branch contains the code that included those (but is no longer maintained).

Screenshots

Inline form validation

<img src="https://raw.githubusercontent.com/mikestefanello/readmeimages/main/pagoda/inline-validation.png" alt="Inline validation"/>

Switch layout templates, user registration

<img src="https://raw.githubusercontent.com/mikestefanello/readmeimages/main/pagoda/register.png" alt="Registration"/>

Alpine.js modal, HTMX AJAX request

<img src="https://raw.githubusercontent.com/mikestefanello/readmeimages/main/pagoda/modal.png" alt="Alpine and HTMX"/>

User entity list (admin panel)

<img src="https://raw.githubusercontent.com/mikestefanello/readmeimages/main/pagoda/admin-user_list.png" alt="User entity list"/>

User entity edit (admin panel)

<img src="https://raw.githubusercontent.com/mikestefanello/readmeimages/main/pagoda/admin-user_edit.png" alt="User entity edit"/>

Monitor task queues (provided by Backlite via the admin panel)

<img src="https://raw.githubusercontent.com/mikestefanello/readmeimages/main/backlite/failed.png" alt="Manage task queues"/>

Getting started

Dependencies

Ensure that Go is installed on your system.

Getting the code

Start by checking out the repository. Since this repository is a template and not a Go library, you do not use go get.

git clone git@github.com:mikestefanello/pagoda.git
cd pagoda

Installing tools

Several optional tools are available to make development easier for you. This includes Ent code-generator, for generating ORM code, Air CLI, to provide live reloading, and Tailwind CSS CLI, to generate CSS.

If you don't want to use Tailwind and/or Daisy UI, or don't want to use Tailwind's standalone CLI, but rather npm, for example, modify the tailwind-install and css make targets based on your preferences. If the script cannot automatically determine the proper Tailwind package to install, modify the TAILWIND_PACKAGE variable to match your operating system.

To easily install all tools, run make install from the root of the repo. There are also separate make targets for each tool (run make help to list all targets).

Create an admin account

To access the admin panel, you must log in with an admin user and to create your