coconut-leaf/backend/README.md

coconut-leaf Backend

The backend service of coconut-leaf, implemented with Go + Gin, migrated from the old Python Flask backend. The data layer executes SQL directly (no ORM).

Note

Currently only SQLite is fully implemented. MySQL interfaces are placeholders (all endpoints return "not implemented" errors).

Requirements

• Go >= 1.26
• C compiler (cgo): The SQLite driver mattn/go-sqlite3 requires CGO feature.
  • Windows: MSYS2's gcc is recommended.
  • Linux / macOS: System-provided gcc / clang works.
• Ensure CGO_ENABLED=1 before building (usually enabled by default when a C compiler is available).

Build

In the backend/ directory:

go build -o coconut-leaf

Note

The first build compiles SQLite C source code; 1–3 minutes is normal.

On Windows, executables built with MSYS2 depend on MSYS2 runtime libraries (I use MSYS2 UCRT64, so it may include libgcc_s_*, libwinpthread-1.dll, etc.). Either add the DLL directory to PATH or copy those DLLs next to the executable.

Configuration

Uses TOML format, specified via -config parameter. See the full template at coconut-leaf.template.toml in the assets directory.

Command-line Arguments

Argument	Description
-config <PATH>	Required, path to the TOML configuration file
-init	Initialize the system: create tables and the first admin user
-username <NAME>	Used with -init, the initial admin username
-password <PASS>	Used with -init, the initial admin password

-username / -password are required only when -init is specified and are validated (username: [0-9A-Za-z]+, password: all visible ASCII characters, i.e., [!-~]+).

Initialization and Runtime

First Deployment

First deployment includes creating tables and the admin user, then running as usual:

./coconut-leaf --config coconut-leaf.toml --init --username admin --password "your-password"

Normal Runtime

./coconut-leaf --config coconut-leaf.toml

After starting, it listens on web.port. Debug logs are written to stderr in the format [<time>] [<level>] <message> [key=value ...].