# Omry

main: [![builds.sr.ht status](https://builds.sr.ht/~anya_hope/omry/commits/main/.build.yml.svg)](https://builds.sr.ht/~anya_hope/omry/commits/main/.build.yml?)

## Name

Pronounced like 'omni' (but with an 'r' in place of an 'n').

*Note: My initial working name for this project was 'flora', which you may still find in many places in the code and documentation.*

## What is Omry?

**Omry is still in early development. Feel free to try it out, but keep in mind
that things are still rough. Feedback is welcome!**

Omry is a searchable, offline archive of web pages. You can think of it as your personal library, where each "book" is a web page you saved,
so you could come back to it.

Omry stores a copy of the web page, 
which allows you to search within the content of the page (even if you forgot its original website 
or title), and lets you see that page even if the original is gone due
to [link rot.](https://en.wikipedia.org/wiki/Link_rot) If you've ever been in a situation where you knew there was that one article, blog post, or online discussion that you bookmarked, but had
no idea how to find it now, then Omry is for you.

For more details, please see the [extended project description.](description.md)

Omry is free and open source (see [LICENSE](LICENSE)). This means you can take the code and host it anywhere, including your own computer.

*Please note that the documentation, like the rest of the project, is still early and in-progress.*

## Running Omry on your system

### With Docker Compose (recommended) 

At the moment, the easiest way to start the backend stack is to run:

```sh
docker compose up --pull always
```

This will get all the necessary components of the backend (server, database, search) and start them.
The logs will show "Omry is ready" when the backend is ready for the client application to connect to. 

*To run Omry without Docker Compose, see "Additional options for running Omry on your system."*

## Usage

### Interacting with Omry

This repository contains Omry's backend (server, database, and an internal search client for Typesense).

To use Omry, you need a client application. Currently, the most complete client is [omry-cli](https://git.sr.ht/~anya_hope/omry-cli),
an in-progress application that lets you interact with Omry's backend via the terminal. Eventually, my plan is to have a web-based client.

### Saving web pages to Omry

You can save pages to Omry right from your browser. Please see the instructions [here](docs/import_server.md).

## Standing up the backend stack for development

### Manually

```sh
docker compose up --build
```

#### Note for Asahi Linux

If you are using an Aarch64 (ARM64) system with 16KB page sizes on Linux (such as Asahi on Macs with Apple Silicon),
you need to use a different version of the Typesense Docker image.
You can do so by setting this environment variable:

`export OMRY_TYPESENSE_TAG_SUFFIX="-arm64-lg-page16"`

This will use a build of Typesense which supports 16KB page sizes.
For details, see [this GitHub issue.](https://github.com/typesense/typesense/issues/969#issuecomment-3017686123)

### Via testcontainers

For [Testcontainers](https://rust.testcontainers.org), we push the Omry server image
to the local image registry. That way, there is a predictable
place for us to pull the image in tests.

#### Prerequisites

- [elvish](https://elv.sh)

```sh
elvish scripts/push_omry_local.elv
```

## Additional options for running Omry on your system

### Manually

This is useful if you don't want to use Docker.
You will need to run Typesense separately (on the same machine or elsewhere),
and set the necessary environment variables for Omry to connect to it.

```sh
cargo install --path server
```

This will install the binary `omry-server` to your system. To run it, use

```sh
FLORA_DATABASE_URL=omry.db FLORA_TYPESENSE_API_KEY=flora FLORA_TYPESENSE_URL=http://localhost:8108 omry-server   
```

You may need to change the above values to fit your environment.

### With Docker (no Compose)

This is only useful if you don't want to use Docker Compose. As with the manual
installation, you'll need to run Typesense separately, and pass the right
environment variables to the omry-server container when you run it.

```sh
docker build -t omry-server:latest .
```

## Development

### Prerequisites

- Latest stable Rust toolchain
- [cargo-nextest](https://nexte.st)
- [insta](https://insta.rs)
- Docker, for running Typesense integration tests (Podman is currently not compatible)
  - The Docker daemon must be running for Testcontainers to work.
- *(Optional)* For checking code or running tests on changes: [bacon](https://dystroy.org/bacon/)
    - `cargo install --locked bacon`

### Testing

Assuming you are in the repo root:

`cargo nextest run`

To run tests for individual crates that make up the omry workspace, simply navigate to that directory, and
run tests from there.

For example:

```shell
cd db
cargo nextest r
```

This will only run the tests in the `flora-db` crate.

## Running tests on code changes

**Prerequisites**

- [`bacon`](https://dystroy.org/bacon/)

```
bacon nextest --all-features -- --all-targets
```

## License

Omry, a searchable archive of web pages.
Copyright (C) 2025  Anna 'anya' Hope

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License
along with this program.  If not, see <https://www.gnu.org/licenses/>.

