# librenotes

[![CI](https://git.librete.ch/public/librenotes/actions/workflows/ci.yml/badge.svg)](https://git.librete.ch/public/librenotes/actions)

Cloud-native, multi-tenant notes application. A fork of
[Notesium](https://github.com/alonswartz/notesium) extended with
authentication, per-user data isolation, sync, and PWA support so it can
run as a hosted service at [librenot.es](https://librenot.es).

> **Deploy / operate on netcup:** see [DEPLOY.md](DEPLOY.md) (canonical netcup runbook).

## Features

- Markdown notes with bi-directional links (Zettelkasten / evergreen notes)
- Embedded web app — no Electron, no Node runtime, single static binary
- Multi-tenant backend with magic-link authentication (in development)
- Offline-capable PWA with background sync (planned, Phase 4)

## Build

Requires Go 1.20 or later.

```sh
go build ./cmd/librenotes
```

This produces a `librenotes` binary in the current directory. The web
frontend and shell completion are embedded into the binary at compile
time, so no extra files are needed at runtime.

A Makefile with `build`, `test`, `run`, and `clean` targets is provided
for convenience:

```sh
make build
make test
```

## Run

```sh
./librenotes web --notes-dir ~/notes
```

See `./librenotes help` for the full command list.

## Development setup

A Nix flake provides a reproducible development environment with Go,
build tools, and the project CLIs. Use the plain `dev` shell for a
non-sandboxed Go toolchain:

```sh
nix develop .#dev
```

Alternatively, build a Docker-based dev environment:

```sh
docker build -f Dockerfile.dev -t librenotes-dev .
docker run --rm -it -v "$PWD:/workspace" librenotes-dev
```

The repository layout follows the standard Go project structure:

```
cmd/librenotes/      Binary entry point
internal/notesium/   Core notes package (forked from Notesium)
internal/notesium/web/   Embedded frontend assets
```

The Go module path is `git.librete.ch/public/librenotes`.

## Fork attribution

librenotes is a fork of [Notesium](https://github.com/alonswartz/notesium)
by Alon Swartz, used and redistributed under the MIT License. See
[NOTICE](./NOTICE) for the upstream commit hash at fork time and
instructions for tracking upstream changes.

## Documentation

- [User guide](./docs/user-guide.md)
- [Self-hosting](./docs/self-hosting.md)
- [API reference](./docs/api.md)
- [Operations](./docs/operations.md)

## Contributing

See [CONTRIBUTING.md](./CONTRIBUTING.md) for setup, conventions, and
the PR process. By participating you agree to the
[Code of Conduct](./CODE_OF_CONDUCT.md).

## License

MIT — see [LICENSE](./LICENSE). Copyright is shared between the original
Notesium author and the librenotes contributors.