Omry

current branch:

main repo

Mirrors:

• SourceHut
• Codeberg

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

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

Changes introduced in new versions are documented in the changelog.

Omry is still in development. Feel free to try it out, but keep in mind that there could be rough edges and breaking changes. Feedback is welcome!

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

Running Omry on your system

With Docker Compose (recommended)

Note for WSL: I recommend using Docker Desktop with WSL integration, 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.

Generate an authentication token

omry-server requires you to provide an authentication token. This token will be needed for all RPC requests from the client.

If you have the pwgen tool, you can generate one like this:

pwgen -s 20 1

Otherwise, on Linux/macOS you can generate one like this:

LC_ALL=c tr -dc A-Za-z0-9 </dev/urandom | head -c 20; echo

You can specify any other length instead of 20.

Start the server

OMRY_AUTH_TOKEN=<your_generated_token> 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 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, this is omry-cli, a terminal client.

Saving web pages to Omry

You can save pages to Omry right from your browser. Please see the instructions here:

• Desktop
• Android: You can use any browser that supports extensions (e.g. Firefox, Titanium, etc.), and follow the instructions for for the desktop.
• iOS

Keeping in touch/Reporting problems

• Release announcements: https://forgejo.e37a.net/flora/omry/releases
• Issues:
  • main repo
  • Codeberg mirror (either is fine!)

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.

cargo install --path server

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

OMRY_DATABASE_URL=omry.db OMRY_AUTH_TOKEN=<your-token> OMRY_TYPESENSE_API_KEY=omry OMRY_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.

docker build -t omry-server:latest .

docker run -it --name omry \
--net=host \
-e OMRY_AUTH_TOKEN="<your-token>" \
-e OMRY_TYPESENSE_URL=http://localhost:8108 \
-e OMRY_TYPESENSE_API_KEY=omry \
-e OMRY_DATABASE_URL=/data/omry.db \
-v /path/to/db/directory:/data \
localhost:8777/omry-server:latest

Development

Prerequisites

• Latest stable Rust toolchain
• cargo-nextest
• insta
• elvish, 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
  • cargo install --locked bacon

Standing up the backend stack from working copy

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.

Testing

The Omry project uses Testcontainers 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):

elvish scripts/push_omry_local.elv

Then:

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:

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-2026 Lake Hope (also known as Anna 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/.

                                                  
                                                  
                                                  
$$$$$$\ $$$$$$\ $$$$$$\ $$$$$$\ $$$$$$\ $$$$$$\   
\______|\______|\______|\______|\______|\______|  
                                                  
                                                  
                                                  
                                                  
                                                  
                                                  
 $$$$$$\   $$$$$$\ $$\     $$\                  
$$  __$$\ $$  __$$\\$$\   $$  |                 
$$ /  \__|$$ /  $$ |\$$\ $$  /                  
$$ |$$$$\ $$$$$$$$ | \$$$$  /                   
$$ |\_$$ |$$  __$$ |  \$$  /                    
$$ |  $$ |$$ |  $$ |   $$ |                     
\$$$$$$  |$$ |  $$ |   $$ |                     
 \______/ \__|  \__|   \__|                     
                                                
                                                
                                                
$$\      $$\  $$$$$$\  $$$$$$$\  $$$$$$$$\      
$$ | $\  $$ |$$  __$$\ $$  __$$\ $$  _____|     
$$ |$$$\ $$ |$$ /  $$ |$$ |  $$ |$$ |           
$$ $$ $$\$$ |$$$$$$$$ |$$$$$$$  |$$$$$\         
$$$$  _$$$$ |$$  __$$ |$$  __$$< $$  __|        
$$$  / \$$$ |$$ |  $$ |$$ |  $$ |$$ |           
$$  /   \$$ |$$ |  $$ |$$ |  $$ |$$$$$$$$\      
\__/     \__|\__|  \__|\__|  \__|\________|     
                                                
                                                
                                                
                                                
                                                
                                                
$$$$$$\ $$$$$$\ $$$$$$\ $$$$$$\ $$$$$$\ $$$$$$\ 
\______|\______|\______|\______|\______|\______|
                                                  

The author of this software is trans and non-binary, and had to cut through a lot of bullshit to be able to say that in public and with pride. Trans people are hot. Enbies rule.

Made with love and other human emotions.

ASCII font is Big Money-NW by Nathan Bloomfield, via ascii.today.

Typesense® is a registered trademark of Typesense, Inc.