Docker

Docker & Streamlit UI

Run reveilio as a self-contained Streamlit app on localhost:8501. All library features — provider configuration, JD parsing, resume scoring, database storage, and PDF reports — are exposed through a browser UI. No Python install required beyond Docker itself.

📝 When to pick Docker vs. pip: use pip install reveilio if you're building your own Python script or integrating reveilio into a backend. Use Docker if you want a ready-to-use UI for non-developer reviewers, or if you'd rather not manage a Python environment.

---

Requirements

• Docker Engine 24+ (or Docker Desktop on macOS/Windows) with Compose v2.
• 2 GB RAM and ~1 GB disk for the image.
• An API key for one of the supported providers (Gemini, OpenAI, Azure), or a reachable Ollama instance.

---

Quick start

git clone https://github.com/roosterhr/reveilio.git
cd reveilio
docker compose up --build

Then open http://localhost:8501. On first boot the image build takes a couple of minutes; subsequent docker compose up calls use the cache and start in seconds.

---

What you get

A multi-page Streamlit UI backed by the same reveilio library you'd get from PyPI:

Page	What it does
Configure	Pick a provider (Gemini / OpenAI / Azure OpenAI / Ollama) and enter credentials. Optionally connect a database (SQLite / PostgreSQL / MySQL / MongoDB).
Analyze	Upload a job description (PDF, DOCX, DOC, TXT, or paste text) plus a single resume or a zip archive of many. Returns ranked, scored results. Optional one-click save to the connected database.
Database	Browse stored analyses, filter by score / recommendation / candidate / job title, delete records.
Reports	Download polished PDF reports for individual candidates or the full batch ranking.

---

Persistence

The Compose file mounts a named volume reveilio-data at /data inside the container. The default SQLite filepath suggested by the Configure form is /data/reveilio.db, so your analyses survive container restarts.

To wipe all stored analyses:

docker compose down -v

💡 Tip: the -v flag removes the named volume. Without it, docker compose down stops the container but keeps the data for the next run.

---

Connecting to an external database

PostgreSQL, MySQL, and MongoDB are not bundled into the image — you bring your own. In the Configure → Database form:

• On macOS / Windows (Docker Desktop), use host.docker.internal to reach a DB running on your host machine.
• On Linux, use the host's IP on the Docker bridge (usually 172.17.0.1), or run the DB in the same Compose network.
• For a managed DB (e.g. RDS, Cloud SQL, Atlas), use the public hostname as you would from anywhere else.

---

Seeding provider credentials via env vars

If you'd rather not type API keys into the UI each time, pass them into Compose. Any variable set in your shell or .env is forwarded to the container automatically:

# .env next to docker-compose.yml
GEMINI_API_KEY=AIza...
OPENAI_API_KEY=sk-...
OLLAMA_BASE_URL=http://host.docker.internal:11434

The UI form still takes precedence — env vars are just fallbacks, matching the behavior of reveilio.configure() from the library.

---

Updating to a new version

git pull
docker compose up --build

The Compose build respects Docker's layer cache, so only layers downstream of a changed file are rebuilt.

---

Container internals

The image is a single-stage python:3.11-slim with:

• antiword installed for legacy .doc parsing (same system dep called out in Installation).
• The reveilio library installed from source in editable mode with the [all-db] extra so every backend works without rebuild.
• Streamlit and pandas installed from ui/requirements.txt.
• A healthcheck that polls /_stcore/health every 30 seconds.

---

Relationship to the PyPI package

The Docker image and the PyPI wheel are entirely independent distribution channels:

• The wheel (pip install reveilio) contains only src/reveilio/. It does not include the ui/, Dockerfile, or docker-compose.yml.
• Streamlit is not a runtime dependency of the library. It lives only in ui/requirements.txt, installed inside the container.
• New reveilio releases flow the same way as before: tag, build wheel, publish to PyPI. The Docker option is additive.

---

Security notes

• The UI has no authentication. Run it on localhost or behind your own reverse proxy / VPN — do not expose port 8501 to the public internet.
• API keys entered via the form live only in Streamlit session state and are never written to disk.
• Uploaded JDs and resumes are written to tempfile.NamedTemporaryFile paths inside the container and cleaned up by the OS.

---

Continue to Architecture.