Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -3,4 +3,6 @@ tmp
pem
blogs
.DS_Store
*.db
*.db
node_modules
public/css/styles.css
81 changes: 81 additions & 0 deletions CLAUDE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,81 @@
# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Key Development Commands

**Primary Build & Run Commands:**
- `make run` - Run in development mode with live template parsing (`go run -tags=dev ./src/`)
- `make test` - Run Go tests (`go test ./src`)
- `make build` - Production build (includes Tailwind CSS compilation, outputs to `bin/mkblog`)
- `make upload` - Deploy to remote server via SCP

**CSS Development:**
- `make tailwind-build` - Compile Tailwind CSS for production (minified)
- `make tailwind-watch` - Watch mode for Tailwind CSS development

**Database:**
- Uses Goose for migrations with SQLite (`GOOSE_DRIVER=sqlite3`)
- Migration files in `db/migrations/`

## High-Level Architecture

**Core Technology Stack:**
- **Backend**: Go with Chi router, SQLite database (sqlx), structured logging (slog)
- **Frontend**: HTML templates with Tailwind CSS, HTMX for interactivity
- **Authentication**: GitHub OAuth with PKCE for security
- **Deployment**: Caddy reverse proxy with REST API configuration
- **Blog Engine**: Custom mkblog engine for static site generation

**Application Flow:**
1. **Authentication**: GitHub OAuth flow with PKCE verification, session management via cookies
2. **Blog Management**: Users create blogs linked to GitHub repositories
3. **Deployment Pipeline**:
- Downloads repository tarball from GitHub using app installation tokens
- Builds static site using mkblog engine
- Blue/green deployment with atomic symlinks
- Dynamic Caddy configuration for custom subdomains (*.mkblog.dev)

## Key Architectural Patterns

**Build Tags for Environment-Specific Code:**
- Development: Templates parsed on every request (`//go:build dev`)
- Production: Templates pre-compiled at startup (`//go:build !dev`)

**Database Design:**
- Users table with GitHub integration (tokens, user info)
- Blogs table (one blog per user, linked to GitHub repo)
- Deployments table with status tracking and constraints ensuring single pending/running deployment per blog

**Context-Based Request Handling:**
- Middleware injects session and user data into request context
- Type-safe context value helpers with generics
- Authentication middleware validates GitHub tokens on each request

**Template System:**
- Embedded file system for templates in `src/view/`
- Environment-specific rendering (dev vs prod)
- FS configured as `os.DirFS("src/view/templates")` in dev mode
- Template parsing uses `*.html` pattern relative to FS root

## Configuration Requirements

**Essential Environment Variables:**
- `PORT=8080` - Application port
- `DB_SOURCE_NAME=./db/mkblog.db` - SQLite database path
- `GH_CLIENT_ID`, `GH_CLIENT_SECRET` - GitHub OAuth app credentials
- `GH_PRIVATE_KEY_PATH` - GitHub App private key for repository access
- `DPL_SRC_DIR`, `DPL_DIST_DIR` - Deployment directory paths
- `RESERVED_BLOG_NAMES` - Comma-separated list of reserved subdomain names

**External Dependencies:**
- Caddy server running on port 2019 (REST API) and 443 (HTTP server)
- GitHub App installation for repository access
- Node.js/npm for Tailwind CSS compilation

**Development Setup:**
1. Copy `example.env` to `.env` and configure GitHub OAuth
2. Install dependencies: `npm install` (for Tailwind)
3. Run database migrations using Goose
4. Start development server: `make run`
5. Use `make tailwind-watch` for CSS development
12 changes: 9 additions & 3 deletions Makefile
Original file line number Diff line number Diff line change
@@ -1,11 +1,17 @@
include .env

run:
go run ./src/
go run -tags=dev ./src/
test:
go test ./src
build:
build: tailwind-build
env CGO_ENABLED=1 GOOS=${GOOS} GOARCH=${GOARCH} go build -o bin/mkblog ./src
upload:
gtar -czf repo.tar.gz --exclude-vcs-ignores --exclude=repo.tar.gz .
scp -i "${SSH_KEY_PATH}" repo.tar.gz "${SSH_USER}@${SSH_HOST}:/opt/mkblog/repo.tar.gz"
scp -i "${SSH_KEY_PATH}" repo.tar.gz "${SSH_USER}@${SSH_HOST}:/opt/mkblog/repo.tar.gz"

tailwind-build:
npx tailwindcss -i ./src/styles/tailwind.css -o ./public/css/styles.css --minify

tailwind-watch:
npx tailwindcss -i ./src/styles/*.css -o ./public/css/styles.css --watch
Loading