lichenblankie/tinyweb
2
0
Fork 0
Code Issues Pull requests Projects 1 Releases Packages Wiki Activity Actions

restructure README: expand getting started, demote Docker

Browse source
This commit is contained in:
blankie 2026-06-09 03:18:23 +00:00
parent b0ec191777
commit f6f3804126
1 changed files with 46 additions and 63 deletions
Download patch file Download diff file Expand all files Collapse all files

109
README.md
View file

@ -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: