Self-hosting on Searpa Docs

Requirements

Mon, 01 Jan 0001 00:00:00 +0000

Requirements#

Runtime#

Component	Notes
A container runtime	Docker or Podman, to run the published image.
PostgreSQL	The application database. Any reasonably recent PostgreSQL (16+) works.
A Brave Search API key	The minimum for useful results, see Search providers. The free tier is enough to start.
Outbound HTTPS	The server calls upstream providers; if you run behind an allowlist, see the provider hosts.

Everything else, the web server, static-file serving and translation-catalog compilation, is built into the image.

Quick start

Mon, 01 Jan 0001 00:00:00 +0000

Quick start#

The fastest way to a running instance is the Docker image. You need a PostgreSQL database and, at minimum, a Brave Search API key.

With Docker#

docker run -p 8000:8000 \
 -e SECRET_KEY=your-long-random-secret \
 -e DATABASE_URL=postgres://user:password@db-host:5432/searpa \
 -e ALLOWED_HOSTS=search.example.com \
 -e BRAVE_API_KEY=your-brave-key \
 -e BRAVE_SUGGEST_API_KEY=your-brave-suggest-key \
 -e MARGINALIA_API_KEY=public \
 searpa

On start the container:

Applies database migrations (a no-op once the schema is current).
Serves the app with gunicorn (2 workers) on port 8000.
Serves its own static files via WhiteNoise (compressed and hashed), no separate web server or CDN required.
Answers a health check at /up.

The translation catalogs and static files are compiled at build time, so there is nothing else to run.

Configuration

Mon, 01 Jan 0001 00:00:00 +0000

Configuration#

Searpa is configured entirely through environment variables (in production) or a .env file (in development). The repository ships an .env.example documenting every variable; this page is the reference.

Core#

Variable	Purpose	Notes
`SECRET_KEY`	Django secret key	Required in production. Long and random.
`DEBUG`	Debug mode	Keep `False` (the default) in production.
`ALLOWED_HOSTS`	Comma-separated hostnames the app will serve	e.g. `search.example.com`.
`DATABASE_URL`	PostgreSQL connection URL	e.g. `postgres://user:pass@host:5432/searpa`.
`LOG_LEVEL`	Logging verbosity	`DEBUG` / `INFO` / `WARNING` / `ERROR` (default `INFO`).

Search providers#

These keys decide which engines, media tabs and knowledge cards are available. A provider with no key is simply hidden (not shown as broken). Full details on Search providers.

Search providers

Mon, 01 Jan 0001 00:00:00 +0000

Search providers#

Searpa blends results from several independent providers. Which tabs and cards appear depends on which keys you set. A provider with no key is hidden, the affected tab or card simply doesn’t show, rather than displaying an error.

All upstream calls happen server-side; keys are never exposed to the browser.

This page is the overview of which key enables what. For step-by-step signup instructions for each provider, see Getting API keys.

Getting API keys

Mon, 01 Jan 0001 00:00:00 +0000

Getting API keys#

Step-by-step guides for obtaining each provider’s key. None are required to boot Searpa, but at least one web engine (Brave is the easiest) is needed for useful results. Each provider you skip simply hides its tab or card, see Search providers for what each one enables.

Once you have a key, set the matching environment variable (see Configuration) and restart the app.

All of these have a free tier that is generous enough for a personal or small-team instance, Searpa caches aggressively and only calls the paid card APIs when a query actually matches. The shared keys (public for Marginalia, anonymous Stack Exchange) need no signup at all.

Translation

Mon, 01 Jan 0001 00:00:00 +0000

Translation (LibreTranslate)#

The Translate tab is powered by LibreTranslate, an open-source, self-hostable machine-translation server. Searpa calls it server-side, no third-party translation service is involved.

Enabling the tab#

Point Searpa at a LibreTranslate instance with LIBRETRANSLATE_URL:

LIBRETRANSLATE_URL=http://libretranslate:5000

Set it and the Translate tab (and its setting) appear, with whatever languages that instance offers.
Leave it unset and the Translate tab and its setting are disabled entirely.

Running LibreTranslate#

The development stack starts a local LibreTranslate automatically (make up brings one up at http://localhost:5000). For production, run your own, for example:

Users & access

Mon, 01 Jan 0001 00:00:00 +0000

Users & access#

Searpa is login-only with no public registration, so as the administrator you control who has an account. This is what keeps an instance private to your users.

Creating accounts#

Create users with Django’s standard management command:

# Docker
docker exec -it <container> python manage.py createsuperuser

# From source
make superuser

createsuperuser makes an admin account; for ordinary users you can create them the same way (or from the Django admin once you have a superuser). Each account needs a username and password; an email is optional (see below).

API keys

Mon, 01 Jan 0001 00:00:00 +0000

API keys#

Users access the public API with per-user API keys. Users can manage their own keys in the web UI (Settings → API keys), and you can manage them from the command line.

How keys are stored#

A key looks like searpa_sk_<prefix>.<secret>:

The prefix (8 characters) is stored in the clear for fast lookup.
Only a SHA-256 hash of the secret is stored, never the secret itself.

So a key’s full value is shown exactly once, at creation, and cannot be recovered afterwards, only revoked.

Maintenance

Mon, 01 Jan 0001 00:00:00 +0000

Maintenance#

Searpa needs little ongoing care, but a few management commands keep it tidy and current. Run them on a schedule (a cron job, a systemd timer, or your orchestrator’s scheduled-task feature). Run each inside the container (docker exec <container> python manage.py …) or via make / uv run from source.

Scheduled tasks#

Command	What it does	Suggested schedule
`clear_expired_cache`	Deletes expired search-result cache rows	Daily
`check_provider_health`	Probes providers with a free health endpoint so `/status` stays current, without spending paid quota	Every ~10 minutes
`refresh_currency`	Refreshes cached exchange rates and prunes the instant-answer cache	Daily (optional, also self-refreshes on demand)

A cron example:

Production notes

Mon, 01 Jan 0001 00:00:00 +0000

Production notes#

A few things worth knowing when you run Searpa for real users.

The image#

Serves the app with gunicorn (2 workers) on port 8000.
Serves its own static files via WhiteNoise, compressed and hashed, so you don’t need a separate static-file server or CDN.
Compiles translation catalogs and collects static files at build time.
Runs database migrations on start.

Reverse proxy and TLS#

Put a TLS-terminating reverse proxy in front (Caddy, nginx, Traefik, …) and forward to port 8000. Set: