miruzo-core

miruzo-core is the backend and ingest core for the miruzo photo archive. The API serves image listing/context/love endpoints, and the ingest tooling imports gataku assets into supported database backends.

✨ Features

• Go API for image browsing and reaction workflows
• Python ingest pipeline for importing and processing source assets
• Shared support for MySQL, PostgreSQL, and SQLite
• Generated SQL access via sqlc for Go repositories

📏 Why Manbytes?

Human-friendly size units are not universal and are shaped by culture and convention.

miruzo defines manbytes, a size unit based on a 10⁴-byte scale (the Japanese “man” unit), and uses it in API responses for image file sizes.

For details, see docs/unit.md.

🧩 Repository Layout

• miruzo: Go API application, SQL/migrations, Makefile
• miruzo-py: Python ingest services, DB adapters, tests

🚀 Requirements

• Git
• Go 1.26.x (see miruzo/go.mod)
• Python 3.10+ (3.14.x recommended for local development; see miruzo-py/.python-version)
• uv (Python package/dependency manager)

Backend/runtime matrix:

Backend	Version	Go driver	Go API	Python driver
MySQL	8.0.16+ (CHECK)	go-sql-driver/mysql	supported	mysqlclient (MySQLdb)
PostgreSQL	14+	jackc/pgx/v5	supported	psycopg3 (psycopg)
SQLite	3.37.0+ (RETURNING, STRICT)	mattn/go-sqlite3	supported	sqlite3 (stdlib)

Release/distribution notes:

• Official Linux and Windows release binaries are built on Debian 12.
• Linux release binaries target a minimum expected glibc version of 2.36.
• macOS is supported on a best-effort basis, but official release binaries are not provided.

🛠️ Setup

For source development setup, follow CONTRIBUTING.md:

• prerequisites and backend version requirements
• Linux/macOS setup for Go tools and Python DB drivers
• runtime configuration and test environment variables

Prebuilt binary releases are planned. Until then, use source setup.

⚙️ Configuration

Go API (miruzo/config.yaml)

• Base file: miruzo/internal/app/config.sample.yaml
• Local default file: miruzo/config.yaml
• Current Go API backends: mysql, postgresql, sqlite

Python ingest (miruzo-py/.env)

• Copy miruzo-py/.env.development to miruzo-py/.env
• Set these variables explicitly:
  • ENVIRONMENT (development or production)
  • DATABASE_BACKEND (mysql, postgres, or sqlite)
  • DATABASE_URL
    • MySQL: mysql+mysqldb://...
    • PostgreSQL: postgresql+psycopg://...
    • SQLite: sqlite:///...
• Path-related variables (MEDIA_ROOT, PUBLIC_MEDIA_ROOT, GATAKU_ROOT, GATAKU_ASSETS_ROOT, GATAKU_SYMLINK_DIRNAME) can be left as defaults on first setup, then customized only when needed.

🖱️ Run Locally

Start API:

cd miruzo
make dev
# or
cd miruzo && go run ./cmd/miruzo-api

Default API address: http://127.0.0.1:1360/api

Run importer help:

cd miruzo-py
uv run python -m scripts.gataku_import --help

🧪 Testing

Default suites:

cd miruzo && go test ./...
cd miruzo-py && uv run pytest

Focused suites:

cd miruzo && go test ./internal/service/...
cd miruzo && go test ./internal/adapter/persistence/contract/...
cd miruzo && go test -tags integration \
  ./internal/adapter/persistence/mysql \
  ./internal/adapter/persistence/postgres
cd miruzo-py && uv run pytest tests/importers
cd miruzo-py && uv run pytest tests/persist

Optional test database DSN environment variables:

• Go tests:
  • MIRUZO_TEST_MYSQL_URL
  • MIRUZO_TEST_POSTGRES_URL
• Python tests:
  • MIRUZO_PY_TEST_MYSQL_URL
  • MIRUZO_PY_TEST_POSTGRES_URL

📜 License

This project is licensed under GNU GPLv3. See LICENSE.

🤝 Contributing

See:

• AGENTS.md
• CONTRIBUTING.md

🔗 Related Projects

• miruzo-web — Solid.js frontend that consumes the core APIs
• gataku — Source asset repository used by the importer

👤 Contact

miruzo-core is developed and maintained by mntone.

• GitHub: https://github.com/mntone
• Mastodon: https://mstdn.jp/@mntone
• X: https://x.com/mntone