131 lines
4.6 KiB
Markdown
131 lines
4.6 KiB
Markdown
# Trove
|
|
|
|
A federated search engine for the small web. Seeded by fediverse attention, ranked by domain coherence rather than commercial authority.
|
|
|
|
## Tech stack
|
|
|
|
Laravel 13 · Livewire 4 · PostgreSQL 17 (tsvector FTS) · Redis 7 · FrankenPHP · Vite 8 · Tailwind 4.
|
|
|
|
## Local development
|
|
|
|
Requires [Nix](https://nixos.org/download/) and [Podman](https://podman.io/).
|
|
|
|
```sh
|
|
nix-shell # enter dev shell
|
|
dev-up # start app, db, redis
|
|
```
|
|
|
|
App: `http://localhost:8200` · Vite HMR: `http://localhost:5175`
|
|
|
|
Other helpers inside the nix shell: `dev-down`, `dev-rebuild`, `dev-shell`, `dev-artisan <cmd>`, `dev-logs`.
|
|
|
|
## Self-hosting
|
|
|
|
Trove ships as a Docker image published to `forge.lvl0.xyz/lvl0/trove`. You provide the compose/stack config.
|
|
|
|
### Required environment
|
|
|
|
| Variable | Purpose |
|
|
|---|---|
|
|
| `APP_KEY` | Laravel app key. Generate with `docker run --rm forge.lvl0.xyz/lvl0/trove:latest php artisan key:generate --show`. **Must persist across deployments** or sessions/encrypted data break. |
|
|
| `APP_URL` | Public URL, e.g. `https://trove.example.org` |
|
|
| `DB_DATABASE`, `DB_USERNAME`, `DB_PASSWORD` | PostgreSQL credentials |
|
|
| `DB_HOST` | Hostname of the PostgreSQL service. Default `db`. Override if your service is named differently. |
|
|
| `REDIS_HOST` | Hostname of the Redis service. Default `redis`. Override if your service is named differently. |
|
|
|
|
### Services you need to provide
|
|
|
|
- **App**: pull `forge.lvl0.xyz/lvl0/trove:latest` (or a pinned `v*` tag). Exposes port `8000` inside the container. The image runs migrations and warms caches on boot.
|
|
- **Worker**: same image as `app`, with `command: php artisan queue:work --tries=3 --max-time=3600`. Processes the crawler queue (URL fetching, content extraction, retries). Crawls won't actually run without this — `app` only enqueues work. **Required for the crawler to function.**
|
|
- **PostgreSQL 17**. Hostname must be reachable as `db` (default) or set `DB_HOST`. Persist `/var/lib/postgresql/data`.
|
|
- **Redis 7** with `--appendonly yes` (queue jobs persist across restarts). Hostname `redis` or set `REDIS_HOST`.
|
|
|
|
On first boot the startup script waits for PostgreSQL, warms caches, then runs `php artisan migrate --force` automatically. The 60-second wait loop covers slow PG init; it exits with a clear error if PG never becomes reachable.
|
|
|
|
### Volumes
|
|
|
|
- `/app/storage` — Laravel writable paths (logs, cached views, uploads). Persist this.
|
|
|
|
### Healthcheck
|
|
|
|
The image exposes `GET /up` (Laravel's built-in health route). The Dockerfile declares a HEALTHCHECK; your orchestrator can use `curl -fsS http://localhost:8000/up` for liveness.
|
|
|
|
### Example compose stack
|
|
|
|
A minimal reference — adapt for your infra. DockGE, Portainer, `docker compose`, Kubernetes, and bare `podman play kube` all work with equivalent configs.
|
|
|
|
```yaml
|
|
services:
|
|
app:
|
|
image: forge.lvl0.xyz/lvl0/trove:latest
|
|
restart: always
|
|
ports: ["${APP_PORT:-8400}:8000"]
|
|
environment:
|
|
APP_KEY: "${APP_KEY}"
|
|
APP_URL: "${APP_URL}"
|
|
DB_DATABASE: "${DB_DATABASE}"
|
|
DB_USERNAME: "${DB_USERNAME}"
|
|
DB_PASSWORD: "${DB_PASSWORD}"
|
|
volumes:
|
|
- app_storage:/app/storage
|
|
depends_on:
|
|
db: { condition: service_healthy }
|
|
redis: { condition: service_healthy }
|
|
|
|
worker:
|
|
image: forge.lvl0.xyz/lvl0/trove:latest
|
|
restart: always
|
|
command: php artisan queue:work --tries=3 --max-time=3600
|
|
environment:
|
|
APP_KEY: "${APP_KEY}"
|
|
APP_URL: "${APP_URL}"
|
|
DB_DATABASE: "${DB_DATABASE}"
|
|
DB_USERNAME: "${DB_USERNAME}"
|
|
DB_PASSWORD: "${DB_PASSWORD}"
|
|
volumes:
|
|
- app_storage:/app/storage
|
|
depends_on:
|
|
db: { condition: service_healthy }
|
|
redis: { condition: service_healthy }
|
|
|
|
db:
|
|
image: postgres:17-alpine
|
|
restart: always
|
|
environment:
|
|
POSTGRES_DB: "${DB_DATABASE}"
|
|
POSTGRES_USER: "${DB_USERNAME}"
|
|
POSTGRES_PASSWORD: "${DB_PASSWORD}"
|
|
volumes:
|
|
- db_data:/var/lib/postgresql/data
|
|
healthcheck:
|
|
test: ["CMD-SHELL", "pg_isready -U $$POSTGRES_USER -d $$POSTGRES_DB"]
|
|
interval: 10s
|
|
retries: 5
|
|
start_period: 10s
|
|
|
|
redis:
|
|
image: redis:7-alpine
|
|
restart: always
|
|
command: redis-server --appendonly yes
|
|
volumes:
|
|
- redis_data:/data
|
|
healthcheck:
|
|
test: ["CMD", "redis-cli", "ping"]
|
|
interval: 10s
|
|
retries: 5
|
|
|
|
volumes:
|
|
db_data:
|
|
redis_data:
|
|
app_storage:
|
|
```
|
|
|
|
### Upgrades
|
|
|
|
Pull the new image tag, recreate the app container. Migrations run on boot (`php artisan migrate --force` in the startup script). Rollback by pointing at the previous `v*` tag.
|
|
|
|
----
|
|
|
|
AGPL-3.0-or-later. See [LICENSE](LICENSE).
|
|
|
|
Part of [lvl0](https://lvl0.xyz), a collective for horizontal FOSS projects.
|