diff --git a/README.md b/README.md index eca20ee..2405ee0 100644 --- a/README.md +++ b/README.md @@ -7,9 +7,8 @@ A personal, decentralized search engine built on the [Reticulum](https://reticul - [About this project](#about-this-project) - [Features](#features) - [Performance & Scale](#performance--scale) -- [Docker](#docker) -- [Data storage](#data-storage) - [Getting started](#getting-started) +- [Data storage](#data-storage) - [Remote gateway](#remote-gateway) - [How it works](#how-it-works) - [Known rough edges](#known-rough-edges) @@ -71,41 +70,60 @@ propagate to subscribers. - Paginated at 10,000 pages per request - Use `?batch=N` to export in chunks: `/export?batch=0`, `/export?batch=1`, etc. -## Docker +## Getting started -TinyWeb is distributed as source. Clone the repo, then build and run with Docker Compose: +**Requirements:** Python 3.10+ and pip. ```bash git clone https://codeberg.org/tinyweb/tinyweb.git cd tinyweb +pip install -r requirements.txt +python app.py +``` + +Open `http://127.0.0.1:8080` in your browser. The web UI is localhost-only by default. + +Your destination hash is printed on startup — share it with friends so they can subscribe to your index. + +### Command line options + +```bash +python app.py -p 9000 # Use port 9000 instead of default 8080 +python app.py --bind 0.0.0.0 # Expose to your LAN (no auth — see Security) +``` + +### Keeping it running + +```bash +# Terminal session (closes when you log out): +python app.py + +# Background with tmux: +tmux new-session -d -s tinyweb 'python app.py' + +# Background with nohup: +nohup python app.py & +``` + +### Forum plugin (optional) + +```bash +pip install tinyweb-forum +``` + +Enable the forum on the `/style` page. See the [tinyweb-forum README](https://codeberg.org/tinyweb/tinyweb-forum) for details. + +### Docker + +A `docker-compose.yml` is included for containerized setups. Build and run: + +```bash docker compose up -d ``` -The bundled `docker-compose.yml` builds the image from source and persists your data in a named volume: +Data persists in the `tinyweb-data` named volume. On Linux with LAN auto-discovery it works as-is; on macOS or remote setups, see `docker-compose.yml` comments for TCP transport config. -```yaml -services: - tinyweb: - build: . - ports: - - "8080:8080" - volumes: - - tinyweb-data:/data - restart: unless-stopped - -volumes: - tinyweb-data: -``` - -After the first build, the image is cached locally and subsequent `docker compose up -d` calls are instant. To update to the latest source: - -```bash -git pull && docker compose up -d --build -``` - -If you're on macOS or need to reach a Reticulum node over TCP, uncomment the `RNS_TCP_HOST` / `RNS_TCP_PORT` block in `docker-compose.yml` and point it at a host running Reticulum. On Linux with LAN auto-discovery, leave it as-is (or switch to `network_mode: host`). - -### Storage Estimates +## Storage Estimates Average web page content is ~15KB per page: @@ -148,41 +166,6 @@ Back up the whole `~/.tinyweb/` directory periodically. The two files that matte The `/export` page produces a JSON dump of your pages. It's a migration aid — it doesn't preserve your identity file, your custom template, or subscription state. A full restore needs a copy of `~/.tinyweb/`. -### Docker - -When you run via `docker compose up` (above), data is stored in the `tinyweb-data` named volume and persists across rebuilds. To inspect or back up: - -```bash -docker compose exec tinyweb ls -la /data -docker compose down # stop without removing the volume -``` - -To reset everything (destroys your index and identity — back up first): - -```bash -docker compose down -v -``` - -### Command line options - -```bash -python app.py -p 9000 # Use port 9000 instead of default 8080 -python app.py --bind 0.0.0.0 # Expose the web UI to your LAN (see warning below) -``` - -By default, the web UI binds to `127.0.0.1` and is only reachable from the machine running TinyWeb. **The UI has no authentication** — anyone who can reach the port can read, add, and delete entries, and change settings. Only pass `--bind 0.0.0.0` if you fully trust your network, or put TinyWeb behind an authenticating reverse proxy. - -## Getting started - -```bash -pip install -r requirements.txt -python app.py -``` - -This starts the Reticulum server and an HTTP gateway on `http://127.0.0.1:8080`. Open it in your browser. The UI is localhost-only by default; see `--bind` under *Command line options* if you want to reach it from another machine. - -Your destination hash is printed on startup — share it with friends so they can subscribe to your index. - ## Remote gateway To browse a remote TinyWeb instance without running your own index: