coconut-leaf/backend/README.md

# coconut-leaf Backend

The backend service of coconut-leaf, 
implemented with [Go](https://go.dev/) + [Gin](https://gin-gonic.com/), 
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`](https://github.com/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:

```sh
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](../assets/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:

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

### Normal Runtime

```sh
./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 ...]`.