Dependencies/micrach
1
0
Fork 1
mirror of https://github.com/yanislav-igonin/micrach synced 2026-07-27 05:14:17 +03:00
Code Issues Actions Packages Projects Releases Wiki Activity

docs: document modern development workflow

Browse Source
This commit is contained in:
Yanislav Igonin 2026-07-15 23:47:53 +04:00
parent 5b51320db6
commit 33dcfd18ce
2 changed files with 59 additions and 54 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

41
AGENTS.md
View File

@ -52,14 +52,18 @@ so review both paths when changing upload behavior.
## Local Setup and Commands ## Local Setup and Commands
Create a PostgreSQL database, then: Use Go 1.26. From the repository root, copy the development configuration,
start the PostgreSQL 18 service, and run micrach on the host:
```sh ```sh
cp .env.example .env cp .env.example .env
# Edit POSTGRES_URL and normally set IS_DB_SEEDED=false. docker compose up -d db
go run . go run .
``` ```
The example `POSTGRES_URL` matches the Compose service. `make dev` provides
automatic reload and requires `nodemon`.
Common checks: Common checks:
```sh ```sh
@ -67,16 +71,12 @@ go fmt ./...
go test ./... go test ./...
go vet ./... go vet ./...
go build . go build .
GO111MODULE=on CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build . CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o /tmp/micrach-linux-amd64 .
``` ```
`make dev` requires `nodemon`. `sh tests/load.sh` requires Vegeta and targets a `sh tests/load.sh` requires Vegeta and targets a historical public URL by
historical public URL by default; change the target to a controlled environment default; change the target to a controlled environment before use. Do not run
before use. Do not run the load test as routine verification. the load test as routine verification.
The module declares Go 1.15 and CI installs Go 1.17. Avoid language or standard
library features newer than Go 1.17 unless the task also upgrades the supported
Go version and CI configuration.
## Configuration and Generated State ## Configuration and Generated State
@ -120,18 +120,21 @@ Go version and CI configuration.
Check catalog, thread, error, empty, and pagination states as relevant. Check catalog, thread, error, empty, and pagination states as relevant.
- Upload changes: inspect controller transaction flow, `utils/`, repository file - Upload changes: inspect controller transaction flow, `utils/`, repository file
records, original/thumbnail paths, validation limits, and cleanup behavior. records, original/thumbnail paths, validation limits, and cleanup behavior.
- Config changes: update `config/config.go`, `.env.example`, README config table, - Config changes: update `config/config.go`, `.env.example`, and the README
and deployment environment forwarding together. config table together.
- Deployment changes: note that `Dockerfile` expects a prebuilt Linux binary and - Deployment changes:
`docker-compose.yml` assumes Swarm, Traefik, an external network, and a - `Dockerfile` builds the application in a pinned Go builder stage and runs it
persistent host upload mount. as a non-root user in a small runtime image.
- `docker-compose.yml` starts local PostgreSQL only; run micrach on the host.
- CI verifies the project and container build but does not publish or deploy.
## Testing Expectations ## Testing Expectations
There are currently no checked-in Go unit tests and no coverage threshold. Add Go unit tests are checked in across the application packages; there is no
`*_test.go` files beside changed code, use `TestXxx`, and prefer table-driven coverage threshold. Add `*_test.go` files beside changed code, use `TestXxx`,
cases when practical. Repository tests must use disposable test data or a and prefer table-driven cases when practical. Repository tests must use
dedicated database, never a shared production database. disposable test data or a dedicated database, never a shared production
database.
Minimum verification for code changes: Minimum verification for code changes:

70
README.md
View File

@ -21,45 +21,45 @@ provide; the source remains available for local use and development.
## Stack ## Stack
- Go (the module declares Go 1.15; CI builds with Go 1.17) - Go 1.26
- [Fiber v2](https://github.com/gofiber/fiber) - Fiber v2
- PostgreSQL via `pgx` - PostgreSQL 18 for local development
- PostgreSQL access through [`pgx`](https://github.com/jackc/pgx)
- Plain HTML templates and CSS - Plain HTML templates and CSS
## Run locally ## Run locally
### Prerequisites ### Prerequisites
- Go 1.17 or newer - Go 1.26
- PostgreSQL - Docker with Docker Compose
- A PostgreSQL database that the configured user can create tables in - `nodemon` when using automatic reload
### Setup ### Setup
1. Create the database. With standard local PostgreSQL tooling: From the repository root:
```sh
createdb micrach
```
2. Copy the example configuration:
```sh ```sh
cp .env.example .env cp .env.example .env
``` docker compose up -d db
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:
```sh
go run . go run .
``` ```
5. Open [http://localhost:3000](http://localhost:3000), or the port configured The example configuration matches the PostgreSQL 18 service started by
by `PORT`. 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 Startup connects to PostgreSQL, applies missing files from `migrations/`, and
creates the ignored local `uploads/` directory. Uploaded originals and creates the ignored local `uploads/` directory. Uploaded originals and
@ -91,9 +91,6 @@ See [.env.example](.env.example) for a complete example.
## Development commands ## Development commands
```sh ```sh
# Run with automatic restart; requires nodemon.
make dev
# Format, test, vet, and build. # Format, test, vet, and build.
go fmt ./... go fmt ./...
go test ./... go test ./...
@ -101,20 +98,25 @@ go vet ./...
go build . go build .
# Reproduce the Linux CI build. # Reproduce the Linux CI build.
GO111MODULE=on CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go 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 `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 historical public URL, so change it to an environment you own before running
the script. Generated load-test files are ignored by Git. the script. Generated load-test files are ignored by Git.
## Containers and deployment ## Containers and CI
The `Dockerfile` packages a prebuilt `micrach` binary together with templates, The multi-stage `Dockerfile` builds micrach in a pinned Go builder image and
static assets, and migrations. Build the Linux binary before building the runs it as a non-root user in a small runtime image. Verify the image locally:
image. The checked-in `docker-compose.yml` is production-oriented: it expects
Docker Swarm, an existing `web` overlay network, Traefik, a published image, ```sh
and host-mounted upload storage. It is not a standalone local PostgreSQL setup. 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 ## Project layout