Skip to main content

Gojang Documentation

Welcome to the Gojang framework documentation! This guide will help you build modern web applications with Go and HTMX.

Core Concepts​

Architecture: Admin & User Site Separation​

Understanding Gojang's clean architecture

Learn about:

  • Why admin and user sites are completely separated
  • How the generic admin panel works
  • Best practices for maintaining separation
  • Migration guide from mixed architectures

Read this first to understand the framework's design philosophy!

Tutorials​

1. Creating Static Pages​

Learn how to add simple pages without data models

Perfect for:

  • About pages
  • Contact pages
  • Terms of Service
  • FAQ pages

Topics covered:

  • Template structure
  • Handler creation
  • Route registration
  • Custom CSS usage
  • HTMX basics

Time: ~5 minutes per page

2. Quick Start: Adding a Data Model​

The simplest way to add a new data model - perfect for beginners!

Perfect for:

  • Your first model
  • Learning the basics
  • Quick prototyping
  • Simple CRUD apps

Topics covered:

  • Minimal 4-property Product example
  • Step-by-step with code snippets
  • Handler, routes, and views
  • Admin panel integration
  • Testing your model

Time: ~10 minutes

3. Creating Pages with Data Models​

Comprehensive guide for advanced data model features

Perfect for:

  • Complex models with many fields
  • Advanced relationships
  • Custom validation
  • Production applications

Topics covered:

  • Advanced Ent schema features
  • Code generation
  • Database migrations
  • Form validation
  • CRUD handlers
  • Template patterns
  • Admin panel integration
  • Troubleshooting

Time: ~20-30 minutes per model

4. HTMX Integration Patterns​

Master HTMX patterns for building dynamic, interactive user interfaces

Perfect for:

  • Modal dialogs
  • Form submissions
  • CRUD operations
  • Dynamic content loading
  • Real-time updates

Topics covered:

  • Core HTMX attributes
  • Modal dialog patterns
  • Form handling & validation
  • CRUD operations (Create, Read, Update, Delete)
  • Partial templates
  • Event handling
  • Response headers
  • Authentication with HTMX
  • Best practices

Time: ~15-20 minutes to read, lifetime to master

Advanced Guides​

5. Authentication & Authorization Deep Dive​

Master user authentication and authorization in Gojang

Perfect for:

  • User registration and login
  • Session management
  • Password security
  • Access control middleware
  • Role-based permissions
  • Resource ownership checks

Topics covered:

  • User model and password hashing
  • Session-based authentication
  • Login/logout flows
  • Authentication middleware (RequireAuth, RequireStaff)
  • Authorization patterns
  • Security best practices
  • Testing authentication

Time: ~30 minutes to read

6. Deployment Guide​

Deploy your Gojang application to production

Perfect for:

  • Docker containerization
  • VPS deployments (DigitalOcean, Linode)
  • Cloud platforms (AWS, GCP, Azure)
  • PaaS providers (Fly.io, Railway, Heroku)

Topics covered:

  • Building production binaries
  • Docker and Docker Compose setup
  • VPS server configuration
  • Nginx reverse proxy setup
  • SSL/TLS with Let's Encrypt
  • Database setup (PostgreSQL)
  • Process management (systemd)
  • CI/CD pipelines
  • Monitoring and backups

Time: ~45 minutes to read, 1-2 hours to deploy

7. Distributed Deployment & Load Balancing​

Scale your Gojang application with load balancing and distributed deployment

Perfect for:

  • High-traffic applications
  • High availability requirements
  • Horizontal scaling
  • Zero-downtime deployments
  • Multi-server architectures

Topics covered:

  • Distributed deployment capabilities
  • PostgreSQL for shared state
  • Redis for session management
  • Load balancer configuration (Nginx, HAProxy, cloud LBs)
  • Multiple deployment architectures
  • Health checks and monitoring
  • Rolling deployments
  • Best practices and troubleshooting

Time: ~30 minutes to read

8. Logging Guide​

Master structured logging with Zap for production-ready observability

Perfect for:

  • Understanding the logging system
  • Production debugging and monitoring
  • Performance optimization
  • Security audit trails

Topics covered:

  • Zap-based structured logging
  • Formatted vs structured logging
  • Log levels (DEBUG, INFO, WARN, ERROR)
  • Best practices and patterns
  • Handler and middleware logging
  • Production considerations
  • Anti-patterns to avoid

Time: ~10 minutes to read

9. Testing Best Practices​

Write effective tests for your Gojang application

Perfect for:

  • Unit testing
  • Integration testing
  • Handler testing
  • Database testing
  • Test-driven development (TDD)

Topics covered:

  • Testing structure and conventions
  • Unit test patterns
  • Table-driven tests
  • Testing handlers and middleware
  • Database test setup
  • Mock objects and test doubles
  • Test fixtures and helpers
  • Benchmarking
  • Code coverage
  • CI/CD integration

Time: ~25 minutes to read

10. Rendering Primitives Guide​

Build reusable template functions, partials, and components

Perfect for:

  • Reusable UI components
  • Shared template functions
  • Direct partial rendering
  • Generic table and pagination rendering

Topics covered:

  • Common template function map
  • Component template loading
  • RenderPartial and RenderComponent
  • Generic table component
  • Best practices for reusable view models

Time: ~15 minutes to read

11. Security Features 🔒​

Comprehensive overview of implemented security features

Perfect for:

  • Understanding security implementations
  • Production deployment preparation
  • Security compliance verification
  • Security feature reference

Topics covered:

  • Authentication & password security (Argon2id)
  • Session management & CSRF protection
  • Rate limiting with proper IP handling
  • Security headers (including HSTS)
  • Input validation & database security
  • HTTPS enforcement
  • Audit logging
  • Security disclosure (security.txt)
  • CI/CD security scanning

Time: ~10 minutes to read

12. Taskfile Commands Guide​

Master the Task automation commands for database migrations and development

Perfect for:

  • Database migrations
  • Development workflow automation
  • Understanding available commands
  • Migration best practices

Topics covered:

  • Installing Task
  • Database migration commands (migrate, migrate-down, migrate-create)
  • Other development commands (build, test, dev, etc.)
  • Migration workflow
  • Best practices and troubleshooting
  • Common migration patterns

Time: ~15 minutes to read

Documentation Structure​

docs/
├── README.md                           # This file - Documentation index
├── architecture-separation.md          # Guide: Admin & User site separation
├── creating-static-pages.md            # Tutorial: Static pages
├── quick-start-data-model.md           # Tutorial: Simple data model (START HERE!)
├── creating-data-models.md             # Tutorial: Data models & CRUD (comprehensive)
├── htmx-patterns.md                    # Guide: HTMX integration patterns
├── rendering-primitives-guide.md       # Guide: Reusable rendering primitives
├── authentication-authorization.md     # Guide: Auth & authorization
├── deployment-guide.md                 # Guide: Production deployment
├── distributed-deployment.md           # Guide: Load balancing & distributed setup
├── logging-guide.md                    # Guide: Logging Guide
├── testing-best-practices.md           # Guide: Testing strategies
├── SECURITY-SUMMARY.md                 # Guide: Security features overview
└── taskfile-guide.md                   # Guide: Task commands & migrations

Framework Architecture​

Project Structure​

app/
├── cmd/                     # Application commands
│   ├── migrate/
│   ├── seed/
│   └── web/
├── gojang/                  # Framework core, admin, auth, generated models, renderers
│   ├── admin/               # Admin panel and admin templates
│   ├── http/                # Core handlers, middleware, and routes
│   ├── models/              # Generated Ent code and migrations
│   └── views/               # Framework renderer and embedded FS wiring
├── pages/                   # App-owned page handlers and routes
├── schema/                  # Ent schema definitions
├── posts/                   # App-owned post handlers, routes, and templates
└── views/                   # Public shared templates, static assets, translations, forms

Key Concepts​

Template Rendering​

Templates use Go's html/template with two required blocks:

{{define "title"}}Page Title{{end}}

{{define "content"}}
<!-- Your content here -->
{{end}}

Base template (base.html) provides:

  • Header with navigation
  • Footer
  • Flash messages
  • HTMX integration

Handlers​

Handlers follow this pattern:

func (h *Handler) Action(w http.ResponseWriter, r *http.Request) {
    // 1. Parse input
    // 2. Validate
    // 3. Process (database operations)
    // 4. Render response
}

Routes​

Routes are organized by feature:

func FeatureRoutes(handler *FeatureHandler, sm *scs.SessionManager, client *models.Client) chi.Router {
    r := chi.NewRouter()

    r.Get("/feature", handler.List)

    r.Group(func(r chi.Router) {
        r.Use(middleware.RequireAuth(sm, client))
        r.Post("/feature", handler.Create)
    })

    return r
}

Admin Panel​

The admin panel discovers generated Ent models from *models.Client and provides an automatic CRUD workspace. Use RegisterModel only for optional admin overrides:

registry.RegisterModel(ModelRegistration{
    ModelType:      &models.YourModel{},
    Icon:           "🎯",
    NamePlural:     "Your Models",
    ListFields:     []string{"ID", "Name", "CreatedAt"},
    ReadonlyFields: []string{"ID", "CreatedAt"},
})

No custom admin code is needed for a plain generated model.

Common Patterns​

Authentication Required​

r.Group(func(r chi.Router) {
    r.Use(middleware.RequireAuth(sm, client))
    r.Get("/protected", handler.Protected)
})

Staff/Admin Only​

r.Group(func(r chi.Router) {
    r.Use(middleware.RequireAuth(sm, client))
    r.Use(middleware.RequireStaff)
    r.Get("/admin-only", handler.AdminOnly)
})

Get Current User​

user := middleware.GetUser(r.Context())
if user == nil {
    // Not logged in
}

Form Validation​

var form forms.MyForm
if err := forms.Decode(r, &form); err != nil {
    // Handle decode error
}

if err := forms.Validate(r.Context(), &form); err != nil {
    // Handle validation errors
}

HTMX Partial Response​

if r.Header.Get("HX-Request") == "true" {
    // Return just the fragment
    h.Renderer.Render(w, r, "partial.html", data)
} else {
    // Return full page
    h.Renderer.Render(w, r, "full.html", data)
}

Development Workflow​

1. Adding a New Feature​

  1. Create Ent schema (if needed)
  2. Generate code: go generate ./app/gojang/models
  3. Create handler
  4. Create routes
  5. Create templates
  6. Confirm admin auto-discovery; add an admin override only if needed
  7. Test!

2. Running the App​

# Development (basic)
go run ./app/cmd/web

# Development with live reload (recommended)
task dev

# Using task commands
task build            # Build the application
task run              # Build and run
task test             # Run tests

# Build for production
go build -o app ./app/cmd/web
./app

To enable live reload (recommended for development):

Install Air:

go install github.com/air-verse/air@latest

Then run:

task dev
# or
air

Air will automatically restart your server when you save changes to your Go files!

3. Database Migrations​

Auto-migration runs on startup, but you can also use the migrate commands:

# Apply all pending migrations
task migrate

# Rollback last migration
task migrate-down

# Create a new migration
task migrate-create name=add_new_table

See the Taskfile Commands Guide for detailed migration documentation.

4. Testing​

# Run all tests
go test ./...

# Test specific package
go test ./app/pages

# With coverage
go test -cover ./...

Useful Commands​

# Generate Ent code after schema changes
go generate ./app/gojang/models

# Format code
go fmt ./...

# Check for issues
go vet ./...

# Update dependencies
go mod tidy

# Build
go build -o web.exe ./app/cmd/web

# Run
./web.exe

Configuration​

Environment variables in .env:

# Server
DEVHOST=0.0.0.0
PORT=8080
DEBUG=true

# Database
DATABASE_URL=sqlite://./dev.db

# Session
SESSION_KEY=your-secret-key-here

Best Practices​

Security​

✅ DO:

  • Use middleware.RequireAuth for protected routes
  • Validate all user input
  • Use CSRF protection (built-in)
  • Hash passwords (use utils.HashPassword)
  • Sanitize HTML output (built-in)

❌ DON'T:

  • Store passwords in plain text
  • Trust user input
  • Expose sensitive data in logs
  • Skip validation

Code Organization​

✅ DO:

  • One handler per model/feature
  • One route file per feature
  • Group related templates in folders
  • Use meaningful names

❌ DON'T:

  • Put everything in main.go
  • Mix concerns (handlers doing DB + rendering + validation)
  • Use generic names (handler1, page2)

Performance​

✅ DO:

  • Use eager loading for relationships (.WithAuthor())
  • Add database indexes on frequently queried fields
  • Use pagination for large lists
  • Cache static assets

❌ DON'T:

  • Load all records without limit
  • Make N+1 queries
  • Skip indexes on foreign keys

Troubleshooting​

Common Issues​

Problem: Changes not reflecting after edit

  • Solution: Restart the server (or use air for auto-reload)

Problem: Template not found

  • Solution: Check file exists in app/views/templates/ and name matches

Problem: Database locked error

  • Solution: Close other connections to the SQLite database

Problem: Build errors after schema change

  • Solution: Regenerate Ent code:
    go generate ./app/gojang/models

Problem: 404 on route

  • Solution: Check route is registered in main.go and server restarted

Getting Help​

  1. Check the tutorials - Most common tasks are covered
  2. Read existing code - Look at User and Post models for examples
  3. Check documentation:
  4. Open an issue on GitHub