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 (the module declares Go 1.15; CI builds with Go 1.17)
• Fiber v2
• PostgreSQL via pgx
• Plain HTML templates and CSS

Run locally

Prerequisites

• Go 1.17 or newer
• PostgreSQL
• A PostgreSQL database that the configured user can create tables in

Setup

1. Create the database. With standard local PostgreSQL tooling:

   createdb micrach
   

2. Copy the example configuration:

   cp .env.example .env
   

3. Edit .env. At minimum, make POSTGRES_URL match your local database. For normal development, set IS_DB_SEEDED=false; when true, sample rows are inserted every time the application starts.

4. Start the application from the repository root:

   go run .
   

5. 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

# Run with automatic restart; requires nodemon.
make dev

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

# Reproduce the Linux CI build.
GO111MODULE=on CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build .

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 deployment

The Dockerfile packages a prebuilt micrach binary together with templates, static assets, and migrations. Build the Linux binary before building the image. The checked-in docker-compose.yml is production-oriented: it expects Docker Swarm, an existing web overlay network, Traefik, a published image, and host-mounted upload storage. It is not a standalone local PostgreSQL setup.

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