melosh/mal
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: tighten code blocks, add mise install option

Browse Source
This commit is contained in:
mkelvers
2026-05-06 19:43:54 +02:00
parent a6198fce10
commit 7fac75d17f
1 changed files with 33 additions and 47 deletions
Download Patch File Download Diff File Expand all files Collapse all files

80
README.md
View File

@@ -65,65 +65,56 @@ The codebase follows standard Go project layout conventions.
## Getting started ## Getting started
For local development, install Go `1.25+` and Bun, then build frontend assets and run the server. The app requires Go `1.25+`, Bun, and a Playback proxy secret. Choose an installation method:
### Automatic (mise)
```bash ```bash
bun install # Install Bun dependencies curl https://deb.nodesource.com/setup_20.x | sudo bash
bun run build:css && bun run build:ts # Build frontend assets (CSS and TypeScript) mise install
PLAYBACK_PROXY_SECRET="your-32+char-secret" go run ./cmd/server # Run the Go server
``` ```
The frontend pipeline uses Tailwind CSS v4 (`static/style.css`) and TypeScript sources in `static/*.ts`, then emits build artifacts into `dist/` for serving. ### Manual
When the server starts, the app is available at `http://localhost:3000`. Install [Go](https://go.dev/dl), [Bun](https://bun.sh), and [just](https://github.com/casey/just).
### Creating a user
The app has no public registration. Use the built-in CLI command to create a user:
```bash ```bash
git clone https://github.com/mkelvers/mal.git && cd mal
openssl rand -base32 32
PLAYBACK_PROXY_SECRET="your-32-char-secret" go run ./cmd/server
go run ./cmd/server create-user <username> <password> go run ./cmd/server create-user <username> <password>
# or with a built binary:
./server create-user <username> <password>
``` ```
If the username already exists, you will be prompted to confirm overwriting the password. The app runs at `http://localhost:3000`.
### Justfile ### Tasks
Common tasks are automated via the `justfile`. Run `just <task>` after installing [`just`](https://github.com/casey/just): The justfile automates common tasks:
| Task | Description |
| --- | --- |
| `just fmt` | Format Go code |
| `just lint` | Run go fmt and go vet |
| `just test` | Run Go tests |
| `just build` | Full build (Go binary, CSS, TS) |
| `just check` | Run all checks (lint, test, typecheck, build) |
| `just dev` | Build and start the server |
| `just install-hooks` | Install lefthook pre-push hooks |
For containerized usage:
```bash ```bash
docker build -t myanimelist . just fmt # format go code
docker run --rm -p 3000:3000 -e PLAYBACK_PROXY_SECRET="your-32+char-secret" myanimelist just lint # go fmt && go vet
just test # run go tests
just build # build go binary + frontend
just check # lint, test, typecheck, build
just dev # build and run
just install-hooks # install pre-push hooks
``` ```
For persistent data in containers, set `DATABASE_FILE` to `/app/data/mal.db` and mount a volume: ### Docker
```bash ```bash
docker run --rm \ docker build -t mal .
-p 3000:3000 \ docker run --rm -p 3000:3000 -e PLAYBACK_PROXY_SECRET="$(openssl rand -base32 32)" mal
# persistent data
docker run --rm -p 3000:3000 \
-e DATABASE_FILE=/app/data/mal.db \ -e DATABASE_FILE=/app/data/mal.db \
-e PLAYBACK_PROXY_SECRET="your-secret" \
-v "$(pwd)/data:/app/data" \ -v "$(pwd)/data:/app/data" \
myanimelist mal
```
After the container is running, exec into it to create a user: docker exec mal /server create-user <username> <password>
```bash
docker exec <container> /server create-user <username> <password>
``` ```
## Configuration ## Configuration
@@ -136,21 +127,16 @@ docker exec <container> /server create-user <username> <password>
| `MIGRATIONS_DIR` | _(auto-discovered)_ | Optional explicit path to migration files | | `MIGRATIONS_DIR` | _(auto-discovered)_ | Optional explicit path to migration files |
| `PLAYBACK_PROXY_SECRET` | _(required)_ | HMAC secret for signed playback proxy tokens (min 32 chars) | | `PLAYBACK_PROXY_SECRET` | _(required)_ | HMAC secret for signed playback proxy tokens (min 32 chars) |
## Database and testing ## Testing
Migrations run at startup automatically. Schema history includes auth, watchlist, anime metadata, relation tracking, Jikan cache persistence, and retry-queue support. Run locally with `just check` or manually:
There is no CI workflow, so validation is local. Use `just check` to run all checks (lint, test, typecheck, build) or `just install-hooks` to set up the pre-push hook that runs them automatically before each push.
> [!NOTE]
> [`just`](https://github.com/casey/just) must be installed first (e.g. `brew install just`).
Alternatively, run tests manually with:
```bash ```bash
go test ./... go test ./...
``` ```
Migrations run automatically on startup.
## Security ## Security
Keep secrets out of version control, do not publish real credentials in documentation or screenshots, and report security issues privately before public disclosure. Keep secrets out of version control, do not publish real credentials in documentation or screenshots, and report security issues privately before public disclosure.