70 lines
2.3 KiB
Markdown
70 lines
2.3 KiB
Markdown
# 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 ...]`.
|