micrach

micrach is a small, server-rendered imageboard written in Go. It provides one board where visitors can create threads, reply with text or images, bump or sage threads, and browse the thread catalog without a client-side SPA.

The project began as a Go learning project and as an experiment in building a lightweight imageboard with very little JavaScript. The former public instance is offline because it required more moderation than the maintainer could provide; the source remains available for local use and development.

Features

• Server-rendered HTML using Fiber templates
• Thread creation, replies, catalog pagination, bump limits, and sage
• JPEG and PNG uploads with generated thumbnails
• Optional CAPTCHA and request rate limiting
• Automatic PostgreSQL migrations on startup
• Automatic archival when the active-thread limit is reached
• Optional registration with an external board gateway

Stack

• Go 1.26
• Fiber v3
• PostgreSQL 18 for local development
• PostgreSQL access through pgx
• Plain HTML templates and CSS

Run locally

Prerequisites

• Go 1.26
• Docker with Docker Compose
• nodemon when using automatic reload

Setup

From the repository root:

cp .env.example .env
docker compose up -d db
go run .

The example configuration matches the PostgreSQL 18 service started by Compose. Compose runs PostgreSQL only; the micrach application runs on the host. Edit .env when you need different local settings. For normal development, keep IS_DB_SEEDED=false; when true, sample rows are inserted every time the application starts.

For automatic reload, install nodemon, start PostgreSQL as shown above, and run:

make dev

Open http://localhost:3000, or the port configured by PORT.

Startup connects to PostgreSQL, applies missing files from migrations/, and creates the ignored local uploads/ directory. Uploaded originals and thumbnails are stored on disk, so keep that directory persistent when running the service in a container.

Configuration

.env is loaded automatically and is ignored by Git.

Variable	Default in code	Purpose
ENV	release	Runtime mode. production enables CSS filename rewriting at startup.
PORT	3000	HTTP listen port.
POSTGRES_URL	postgresql://localhost/micrach	PostgreSQL connection URL.
IS_DB_SEEDED	false	Insert sample posts at startup. Avoid enabling repeatedly.
IS_RATE_LIMITER_ENABLED	true	Enable Fiber request limiting.
THREADS_MAX_COUNT	50	Maximum active threads before old threads are archived.
THREAD_BUMP_LIMIT	500	Reply count after which a thread no longer bumps.
IS_CAPTCHA_ACTIVE	true	Require CAPTCHA for new threads and replies.
GATEWAY_URL	empty	External gateway base URL. Empty disables gateway integration.
GATEWAY_API_KEY	empty	Shared key used for gateway registration and /api/ping.
GATEWAY_BOARD_ID	empty	Board identifier sent to the gateway.
GATEWAY_BOARD_URL	empty	Parsed from the environment but not currently used by the gateway client.
GATEWAY_BOARD_DESCRIPTION	empty	Board description sent to the gateway.

See .env.example for a complete example.

Development commands

# Format, test, vet, and build.
go fmt ./...
go test ./...
go vet ./...
go build .

# Reproduce the Linux CI build.
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o /tmp/micrach-linux-amd64 .

tests/load.sh is an optional Vegeta load test. Its checked-in target is a historical public URL, so change it to an environment you own before running the script. Generated load-test files are ignored by Git.

Containers and CI

The multi-stage Dockerfile builds micrach in a pinned Go builder image and runs it as a non-root user in a small runtime image. Verify the image locally:

docker build -t micrach:local .

CI checks formatting, tests, vet, native and Linux builds, reachable vulnerabilities, and Docker image construction. It has read-only repository permissions and does not publish or deploy images.

Project layout

controllers/   HTTP handlers and request validation flow
repositories/  PostgreSQL queries and view data types
db/            connection pool and migration runner
config/        environment parsing
gateway/       optional external gateway integration
templates/     server-rendered pages, components, and head fragments
static/        CSS, icons, and error images
uploads/       runtime uploads (created locally, ignored by Git)
migrations/    ordered PostgreSQL schema changes
tests/         optional load-test scripts

Screenshot

License

MIT