proverbes12x/blog-api

By proverbes12x

•Updated 3 months ago

⚡ Stackriv Blog API — Go REST API for a self-hosted blog

Image

183

Overview Tags

proverbes12x/blog-api repository overview

⁠Stackriv Blog API

A production-ready self-hosted REST API for a blog platform — built with Go (stdlib only).

Docker Pulls Docker Image Size

⁠Overview

Stackriv Blog API is a self-hosted REST API powering the Stackriv blog platform. Built with Go standard library only — no framework, no ORM, just clean and maintainable Go code.

⁠Features

✅ JWT authentication with refresh token rotation
✅ Role-based access control (admin / author / reader)
✅ Articles with slug, categories, tags, reading time estimation
✅ Nested comments with moderation
✅ Image upload via MinIO
✅ Newsletter with email confirmation and unsubscribe
✅ Graceful shutdown
✅ Automatic database migrations
✅ Pagination, filtering, search on articles
✅ Multi-arch Docker image (linux/amd64, linux/arm64)

⁠Tech Stack

Layer	Technology
Language	Go 1.25 (stdlib only)
Database	PostgreSQL 16
Storage	MinIO
Auth	JWT + Refresh tokens
Email	SMTP
Container	Docker + Docker Compose

⁠Quick Start

# Clone
git clone https://github.com/stackriv/blog-api.git
cd blog-api
 
# Configure
cp .env.example .env
# Edit .env with your values
 
# Start dependencies
docker compose up -d postgres minio
 
# Run
go run .

Docker Compose (full stack):

services:
  api:
    image: proverbes12x/blog-api:latest
    ports:
      - "127.0.0.1:8080:9006"
    env_file: .env
    depends_on:
      postgres:
        condition: service_healthy

  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: postgres-username
      POSTGRES_PASSWORD: postgres-password
      POSTGRES_DB: blog
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      retries: 5
 
  minio:
    image: minio/minio:latest
    command: server /data --console-address ":9001"
    environment:
      MINIO_ROOT_USER: minioadmin
      MINIO_ROOT_PASSWORD: minioadmin
    volumes:
      - minio_data:/data
 
volumes:
  postgres_data:
  minio_data:

⁠Environment Variables

# App
APP_PORT=9006
APP_ENV=development
APP_URL=https://blog.example.com
 
# Database
DB_HOST=localhost
DB_PORT=5432
DB_USER=postgres-username
DB_PASSWORD=postgres-password
DB_NAME=blog
DB_SSL_MODE=disable
 
# JWT
JWT_SECRET=your-super-secret-key
JWT_EXPIRY=24h
JWT_REFRESH_EXPIRY=168h
 
# MinIO
MINIO_ENDPOINT=localhost:9000
MINIO_ACCESS_KEY=minioadmin
MINIO_SECRET_KEY=minioadmin
MINIO_BUCKET=blog
MINIO_USE_SSL=false
 
# SMTP
SMTP_HOST=smtp.example.com
SMTP_PORT=465
[email protected]
SMTP_PASSWORD=your-app-password
[email protected]

⁠API Reference

⁠Auth

POST   /api/stackriv/v1/auth/register
POST   /api/stackriv/v1/auth/login
POST   /api/stackriv/v1/auth/refresh
POST   /api/stackriv/v1/auth/logout
GET    /api/stackriv/v1/auth/me
PUT    /api/stackriv/v1/auth/me
PUT    /api/stackriv/v1/auth/me/password

⁠Articles

GET    /api/stackriv/v1/articles
GET    /api/stackriv/v1/articles/{slug}
POST   /api/stackriv/v1/articles           # author / admin
PUT    /api/stackriv/v1/articles/{id}      # author / admin
DELETE /api/stackriv/v1/articles/{id}      # author / admin

Query params: ?status=published&category_id=...&tag_id=...&search=...&page=1&per_page=10

⁠Categories

GET    /api/stackriv/v1/categories
GET    /api/stackriv/v1/categories/{id}
POST   /api/stackriv/v1/categories         # admin
PUT    /api/stackriv/v1/categories/{id}    # admin
DELETE /api/stackriv/v1/categories/{id}    # admin

⁠Tags

GET    /api/stackriv/v1/tags
POST   /api/stackriv/v1/tags               # admin
DELETE /api/stackriv/v1/tags/{id}          # admin

⁠Comments

GET    /api/stackriv/v1/articles/{articleID}/comments
POST   /api/stackriv/v1/comments                       # auth
PUT    /api/stackriv/v1/comments/{id}                  # author / admin
DELETE /api/stackriv/v1/comments/{id}                  # author / admin
GET    /api/stackriv/v1/comments/pending               # admin
PATCH  /api/stackriv/v1/comments/{id}/approve          # admin

⁠Upload

POST   /api/stackriv/v1/upload/image      # author / admin

Accepted: jpeg, png, webp, gif, svg — max 10MB

POST   /api/stackriv/v1/newsletter/subscribe
GET    /api/stackriv/v1/newsletter/confirm?token=...
GET    /api/stackriv/v1/newsletter/unsubscribe?email=...
GET    /api/stackriv/v1/newsletter/subscribers          # admin
POST   /api/stackriv/v1/newsletter/send                 # admin

⁠Health

GET    /health

⁠Project Structure

blog-api/
├── main.go                    ← entry point + graceful shutdown
├── routes.go                  ← all routes
├── go.mod
├── Dockerfile
├── docker-compose.yml
└── internal/
    ├── pkg/                   ← response, validator, jwt, slug, pagination, mailer
    ├── config/                ← database, minio, jwt config
    ├── database/              ← auto migrations (8 tables)
    ├── storage/               ← MinIO upload/delete
    ├── middleware/            ← logging, CORS, recover, auth, roles
    └── business/
        ├── model/             ← user, article, category, tag, comment, subscriber
        ├── dto/               ← request / response DTOs
        ├── mapper/            ← model → response
        ├── repository/        ← SQL queries
        ├── service/           ← business logic
        └── controller/        ← HTTP handlers

⁠Roles & Permissions

Action	reader	author	manager
Read articles / categories / tags	✅	✅	✅
Create / edit own article	❌	✅	✅
Delete own article	❌	✅	✅
Delete any article	❌	❌	✅
Manage categories & tags	❌	❌	✅
Upload images	❌	✅	✅
Comment	✅	✅	✅
Approve comments	❌	❌	✅
Send newsletter	❌	❌	✅

⁠Versioning

Tag	Description
`latest`	Most recent release
`1.0.0`	Specific release — never overwritten

⁠Part of Stackriv

This API is part of the Stackriv homelab infrastructure suite.

Made with ❤️ by Stackriv⁠

Tag summary

Recent tags

Content type

Image

Digest

sha256:281cfe72b…

Size

7.7 MB

Last updated

3 months ago

docker pull proverbes12x/blog-api