mirror of
https://github.com/yanislav-igonin/micrach
synced 2026-07-27 05:14:17 +03:00
db8a46cdf1
* chore: add agents md * docs: expand repository and setup guides * docs: plan project modernization * docs: add Wave 1 implementation plan * test: characterize legacy behavior * build: update Go and Fiber v2 * fix(gateway): preserve duplicate auth behavior * refactor(db): migrate to pgx v5 * refactor: replace deprecated I/O APIs * build: add local PostgreSQL compose * build: add multi-stage image * ci: replace legacy deployment workflow * fix(deps): update vulnerable Go modules * docs: document modern development workflow
143 lines
4.8 KiB
Markdown
143 lines
4.8 KiB
Markdown
# 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 v2
|
|
- PostgreSQL 18 for local development
|
|
- PostgreSQL access through [`pgx`](https://github.com/jackc/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:
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
make dev
|
|
```
|
|
|
|
Open [http://localhost:3000](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](.env.example) for a complete example.
|
|
|
|
## Development commands
|
|
|
|
```sh
|
|
# 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:
|
|
|
|
```sh
|
|
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
|
|
|
|
```text
|
|
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](LICENSE)
|