ocms-go

oCMS

A lightweight content management system built with Go, featuring a modern admin interface, session-based authentication, SQLite storage, and extensible architecture with themes and modules.

Features

Content Management

• Page Management: Create, edit, publish, and version pages with a rich content editor
• Scheduled Publishing: Schedule pages to publish at a future date/time
• Media Library: Upload and manage images, documents, and videos with automatic image processing
  • Automatic thumbnail and variant generation
  • Folder organization
  • Featured image support for pages
• Menu Builder: Create navigation menus with drag-and-drop ordering
  • Hierarchical menu structures
  • Link to pages or external URLs
  • Multiple menu locations
• Full-Text Search: Built-in SQLite FTS5 search for fast content discovery

Taxonomy

• Categories: Organize content with hierarchical categories
• Tags: Add flat taxonomy tags to pages

Forms

• Form Builder: Create contact forms, surveys, and data collection forms
  • Multiple field types (text, email, textarea, select, checkbox, radio)
  • Form submissions management
  • Read/unread status tracking
  • Email notifications

Theme System

• Multiple Themes: Switch between different frontend themes
• Theme Settings: Configurable theme options (colors, layout, etc.)
• Template Override: Themes can customize page templates
• Static Assets: Theme-specific CSS, JavaScript, and images

Module System

• Extensible Architecture: Add custom functionality via modules
• Module Lifecycle: Init, routes, admin routes, and shutdown hooks
• Module Migrations: Modules can have their own database migrations
• Template Functions: Modules can add custom template functions
• Active Status Toggle: Enable/disable modules from admin UI without restart
• Module Translations: Modules can embed their own i18n locale files

REST API

• Full CRUD API: Complete REST API for pages, media, tags, and categories
• API Key Authentication: Secure API access with bearer token authentication
• Permission-Based Access: Fine-grained permissions (read/write per resource)
• Rate Limiting: Per-key and global rate limiting
• API Documentation: Built-in API documentation page

SEO

• Meta Tags: Custom title, description, and keywords per page
• Open Graph: Full Open Graph and Twitter Card support
• Sitemap: Auto-generated sitemap.xml
• Robots.txt: Configurable robots.txt generation
• Canonical URLs: Set canonical URLs to avoid duplicate content
• NoIndex/NoFollow: Control search engine indexing per page

Administration

• User Management: Role-based access control (admin/editor)
• Authentication: Secure session-based authentication with argon2id password hashing
• Event Logging: Comprehensive audit trail for all actions
• Admin Dashboard: Modern responsive UI with HTMX and Alpine.js
  • Statistics overview
  • Recent submissions widget
  • Quick actions
• Cache Management: View cache stats and clear cache
• API Key Management: Create and manage API keys
• SQLite Database: Zero-configuration embedded database with migrations

Multi-Language Support

• Content Translation: Translate pages, categories, and tags into multiple languages
• Language Management: Configure site languages with ISO 639-1 codes
• Translation Linking: Link content across languages for seamless switching
• Language Switcher: Built-in frontend component for language navigation
• URL Prefixes: Language-prefixed URLs (e.g., /ru/about-us)
• RTL Support: Right-to-left language support
• Admin UI Localization: Translatable admin interface (English + Russian included)

Webhooks

• Event System: Trigger webhooks on content events (create, update, delete, publish)
• Delivery Tracking: Monitor delivery status and response codes
• Retry Logic: Exponential backoff retry for failed deliveries
• HMAC Signatures: Secure payloads with HMAC-SHA256 signatures
• Custom Headers: Add custom headers to webhook requests
• Dead Letter Queue: Track permanently failed deliveries
• Event Debouncing: Coalesce rapid-fire events to reduce webhook noise

Import/Export

• JSON Export: Export site content to portable JSON format
• ZIP Export: Include media files in export archives
• Selective Export: Choose which content types to include
• JSON Import: Import content from JSON files
• ZIP Import: Restore media files from archives
• Conflict Resolution: Skip, overwrite, or rename on conflicts
• Dry Run Mode: Preview import changes before applying

Performance

• Multi-Level Caching: In-memory and optional Redis caching
• Redis Support: Distributed caching for multi-instance deployments
• Response Compression: Gzip compression for HTML and JSON responses
• Graceful Shutdown: Clean shutdown with request draining
• Health Check: /health endpoint for monitoring

Prerequisites

• Go 1.21 or later
• Node.js (npm) for frontend dependencies
• sqlc for SQL code generation
• templ for type-safe HTML templates
• goose for database migrations
• Dart Sass for SCSS compilation
• libvips for image processing (required for media library)

Installing libvips

macOS:

brew install vips

Ubuntu/Debian:

sudo apt-get install libvips-dev

Fedora:

sudo dnf install vips-devel

Installation

1. Clone the repository:

   git clone https://github.com/olegiv/ocms-go.git
   cd ocms-go
   

2. Install dependencies:

   go mod download
   

3. Install required tools:

   go install github.com/sqlc-dev/sqlc/cmd/sqlc@latest
   go install github.com/a-h/templ/cmd/templ@latest
   go install github.com/pressly/goose/v3/cmd/goose@latest
   

4. Generate code:

   sqlc generate
   templ generate
   

5. Build assets (installs npm dependencies and compiles SCSS):

   make assets
   

Environment Variables

Development

Quick Start

# Set required environment variable
export OCMS_SESSION_SECRET="your-secret-key-at-least-32-bytes"

# Run with asset compilation
make dev

# Or run without rebuilding assets
make run

Available Make Commands

Default Admin Credentials

On first run with OCMS_DO_SEED=true, the application seeds a default admin user:

• Email: admin@example.com
• Password: changeme1234

Change these credentials immediately after first login.

Docker

Quick Start with Docker

# Clone the repository
git clone https://github.com/olegiv/ocms-go.git
cd ocms-go

# Start with Docker Compose (generates session secret automatically)
OCMS_SESSION_SECRET=$(openssl rand -base64 32) OCMS_DO_SEED=true docker compose up -d

# View logs
docker compose logs -f ocms

Access the admin panel at http://localhost:8080/admin with:

• Email: admin@example.com
• Password: changeme1234

Docker Commands

Volume Mounts

Building the Docker Image

# Build with version info
docker build \
  --build-arg VERSION=$(git describe --tags --always) \
  --build-arg GIT_COMMIT=$(git rev-parse --short HEAD) \
  --build-arg BUILD_TIME=$(date -u +%Y-%m-%dT%H:%M:%SZ) \
  -t ocms:latest .

Production Configuration

Create a .env file for production:

OCMS_SESSION_SECRET=your-secure-secret-key-at-least-32-bytes
OCMS_ENV=production
OCMS_DO_SEED=false
OCMS_ACTIVE_THEME=default

# Optional: Redis caching
OCMS_REDIS_URL=redis://redis:6379/0

# Optional: hCaptcha protection
OCMS_HCAPTCHA_SITE_KEY=your-site-key
OCMS_HCAPTCHA_SECRET_KEY=your-secret-key

Then start with:

docker compose --profile redis up -d

Project Structure

ocms-go/
├── cmd/ocms/             # Application entry point
├── docs/                 # Documentation
│   ├── multi-language.md # Multi-language guide
│   ├── webhooks.md       # Webhooks configuration
│   ├── import-export.md  # Import/export guide
│   └── reverse-proxy.md  # Nginx/Apache/NPM setup
├── internal/
│   ├── auth/             # Password hashing utilities
│   ├── cache/            # Caching layer (memory + Redis)
│   ├── config/           # Configuration loading
│   ├── handler/          # HTTP handlers
│   │   └── api/          # REST API handlers
│   ├── i18n/             # Internationalization (admin UI)
│   ├── imaging/          # Image processing (thumbnails, variants)
│   ├── middleware/       # HTTP middleware (auth, API, rate limiting)
│   ├── model/            # Domain models
│   ├── module/           # Module system (registry, hooks)
│   ├── render/           # Template rendering
│   ├── scheduler/        # Cron-based task scheduler
│   ├── seo/              # SEO utilities (sitemap, robots.txt, meta)
│   ├── service/          # Business logic (media, menus, forms)
│   ├── session/          # Session management
│   ├── store/            # Database layer (sqlc generated)
│   │   ├── migrations/   # Goose SQL migrations
│   │   └── queries/      # sqlc query definitions
│   ├── theme/            # Theme loading and management
│   ├── themes/           # Embedded core themes (default, developer)
│   ├── transfer/         # Import/export functionality
│   ├── util/             # Utility functions (slug generation)
│   └── webhook/          # Webhook system
├── modules/              # Custom modules directory
│   └── example/          # Example module implementation
├── custom/               # User content directory (gitignored)
│   ├── themes/           # Custom themes (override or extend core)
│   └── modules/          # Custom modules (future use)
├── web/
│   ├── static/           # Static assets (CSS, JS)
│   │   └── scss/         # SCSS source files
│   └── templates/        # HTML templates
│       ├── admin/        # Admin panel templates
│       ├── api/          # API documentation templates
│       ├── auth/         # Login/logout templates
│       ├── errors/       # Error pages (404, 403, 500)
│       ├── layouts/      # Base layouts
│       └── partials/     # Reusable components
├── uploads/              # Media uploads directory
├── scripts/              # Build scripts
├── Makefile              # Development commands
├── package.json          # npm dependencies (htmx, alpine.js)
└── sqlc.yaml             # sqlc configuration

REST API

The CMS provides a RESTful API for programmatic access to content.

Authentication

API requests require a Bearer token in the Authorization header:

curl -H "Authorization: Bearer your-api-key" http://localhost:8080/api/v1/pages

Create API keys in the admin panel under Settings > API Keys.

Endpoints

Response Format

{
  "data": { ... },
  "meta": {
    "total": 100,
    "page": 1,
    "per_page": 20
  }
}

Error Format

{
  "error": {
    "code": "validation_error",
    "message": "Validation failed",
    "details": { "title": "Title is required" }
  }
}

Theme Development

Core themes (default, developer) are embedded in the binary. To create a custom theme, add a directory in custom/themes/:

custom/themes/my-theme/
├── theme.json          # Theme configuration
├── templates/
│   ├── layouts/
│   │   └── base.html   # Base layout
│   ├── pages/
│   │   ├── home.html   # Homepage template
│   │   ├── page.html   # Single page template
│   │   └── 404.html    # Not found page
│   └── partials/
│       ├── header.html
│       └── footer.html
└── static/
    ├── css/
    └── js/

To override an embedded theme, create a custom theme with the same name:

custom/themes/default/    # Overrides the embedded 'default' theme

Custom themes with the same name as core themes take priority.

theme.json

{
  "name": "My Theme",
  "version": "1.0.0",
  "author": "Your Name",
  "description": "A custom theme",
  "settings": [
    {
      "key": "primary_color",
      "label": "Primary Color",
      "type": "color",
      "default": "#3b82f6"
    }
  ]
}

Module Development

Create custom modules to extend functionality:

package mymodule

import (
    "database/sql"
    "embed"

    "ocms-go/internal/module"
    "github.com/go-chi/chi/v5"
)

//go:embed locales
var localesFS embed.FS

type MyModule struct {
    module.BaseModule
}

func New() *MyModule {
    return &MyModule{
        BaseModule: module.NewBaseModule("mymodule", "1.0.0", "My custom module"),
    }
}

func (m *MyModule) RegisterRoutes(r chi.Router) {
    r.Get("/my-endpoint", m.handleEndpoint)
}

func (m *MyModule) Migrations() []module.Migration {
    return []module.Migration{
        {
            Version:     1,
            Description: "Create my_table",
            Up: func(db *sql.DB) error {
                _, err := db.Exec("CREATE TABLE my_table (...)")
                return err
            },
        },
    }
}

// TranslationsFS returns embedded locale files for i18n support
func (m *MyModule) TranslationsFS() embed.FS {
    return localesFS
}

Register the module in main.go:

moduleRegistry.Register(mymodule.New())

Module Translations

Modules can embed their own translation files:

mymodule/
├── module.go
├── handlers.go
└── locales/
    ├── en/
    │   └── messages.json
    └── ru/
        └── messages.json

Translation keys should be prefixed with the module name (e.g., mymodule.title).

Module Active Status

Modules can be enabled/disabled from the admin UI at Admin > Modules. When a module is disabled:

• Public routes return 404
• Admin routes redirect to the modules list
• Template functions are not registered
• The module remains initialized but inactive

Testing

Run all tests:

OCMS_SESSION_SECRET=test-secret-key-32-bytes-long!! go test ./...

Run tests with verbose output:

OCMS_SESSION_SECRET=test-secret-key-32-bytes-long!! go test -v ./...

Run tests for a specific package:

OCMS_SESSION_SECRET=test-secret-key-32-bytes-long!! go test -v ./internal/store/...

Check for vulnerabilities:

govulncheck ./...

Claude Code Support Tools

This project uses a shared submodule at .claude/shared containing reusable Claude Code extensions:

• Agents: security-auditor, project-architect, code-quality-auditor
• Commands: commit-prepare, commit-do, security-audit, setup-project-tools
• Global config: CLAUDE.md rules and settings.json templates

Updating the Submodule

To update the shared Claude Code tools to the latest version:

# Using the slash command (recommended)
/update-submodule

# Or manually
git submodule update --remote --merge

After updating, stage and commit the submodule change if you want to keep it:

git add .claude/shared
git commit -m "Update Claude Code shared submodule"

Technology Stack

• Backend: Go 1.21+
• Database: SQLite with goose migrations
• SQL: Type-safe queries with sqlc
• Templates: templ for type-safe HTML
• Frontend: HTMX + Alpine.js
• Rich Text Editor: TinyMCE for content editing
• Styling: Custom SCSS framework
• Authentication: Secure sessions with argon2id password hashing
• Containerization: Docker with multi-stage builds

License

Copyright (C) 2025-2026 Oleg Ivanchenko

GNU General Public License v3.0 - see LICENSE file for details.