omry-service 0.17.0

# 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 throughout the code and documentation.*

## What is Omry?

**Omry is still in early development. Feel free to try it out, but keep in mind
that there could be rough edges, or breaking changes down the line. 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 in-progress.*

Changes introduced in new versions are documented in the [changelog.](CHANGELOG.md)

## Running Omry on your system

### With Docker Compose (recommended) 

***Note for WSL:** I recommend using [Docker Desktop with WSL integration](https://docs.docker.com/desktop/features/wsl/),
as opposed to running Docker itself inside WSL. Running Omry from Docker installed in your WSL distro could
result in problems communicating with Omry services from your Windows host,
e.g. when saving pages from your browser.* 

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

```sh
docker compose up
```

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

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:
- [For the desktop](docs/import_from_browser.md)
- [For iOS](docs/ios.md)

Note: On Android, adding pages should be similar to how it works on the desktop.
However, I don't currently have an Android device, and haven't been able to verify it myself.

## Keeping in touch/Reporting problems

You can use the following mailing lists to stay up to date and give feedback:

- Stay up to date with release announcements (low volume): <https://lists.sr.ht/~anya_hope/omry-announce>
- Discuss using Omry, and report problems: <https://lists.sr.ht/~anya_hope/omry-discuss>



## 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)
- [elvish](https://elv.sh), for running helper scripts
- A recent version of Python 3 (3.12 or newer should work), ditto
- 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`

## Standing up the backend stack from working copy

```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)

### Testing

The Omry project uses [Testcontainers](https://rust.testcontainers.org) for integration tests,
which is configured to pull images from the local container registry.

You can create the local registry, and push the `omry-server` and `omry-import-server` images
to it by running the following script (assuming you are in the repo root):

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

Then:

```sh
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 `omry-db` crate.

### Automatically checking Rust code on file changes

Assuming you have installed `bacon`, as mentioned in "Prerequisites":

#### Linting the code on every change (recommended)

```bacon clippy-pedantic-all```

#### Running tests on code changes (may be very slow due to integration tests)

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

## License and acknowledgements

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/>.

Typesense® is a registered trademark of Typesense, Inc.

Made with love and other human emotions.