document run server workflow

2026-03-26 14:46:22 -07:00
parent 9860a19383
commit 56f4c345cb
2 changed files with 111 additions and 1 deletions
@@ -31,3 +31,99 @@ Use the root `Makefile`:
 - `make go-test` to run Go client tests
 - `make compose-up` to run server + MinIO
 - `make compose-up-dev` to run MinIO only
+- `make run-server` to start host `uvicorn` with `.env` (if present) plus defaults
+
+## Development Server Workflow
+
+This is the recommended local workflow for iterating on the Python server and conversion
+library while keeping MinIO in Docker.
+
+### 1) Prerequisites
+
+- `buf` on your `PATH`
+- `uv` on your `PATH`
+- Docker + Docker Compose
+- Local tools if running server on host (not in container):
+  - LibreOffice (`soffice`)
+  - Poppler (`pdftoppm`)
+
+### 2) Generate typed API code
+
+From repo root:
+
+```bash
+make buf-lint
+make buf-generate
+```
+
+### 3) Sync Python workspace dependencies
+
+From repo root:
+
+```bash
+make py-sync
+```
+
+### 4) Start MinIO dependency stack (dev compose)
+
+From repo root:
+
+```bash
+make compose-up-dev
+```
+
+MinIO endpoints:
+
+- API: `http://localhost:9000`
+- Console: `http://localhost:9001`
+- Default creds: `minioadmin` / `minioadmin`
+
+### 5) Start Connect server (host process)
+
+In a separate terminal, from repo root:
+
+```bash
+make run-server
+```
+
+`make run-server` behavior:
+
+- loads `.env` automatically if present
+- applies reasonable defaults when values are not set
+- defaults MinIO endpoint to `localhost:9000` for host-based development
+- supports optional `UVICORN_HOST` and `UVICORN_PORT` overrides
+
+If you copy from `.env.example`, set `MINIO_ENDPOINT=localhost:9000` for host mode.
+
+Server endpoint base URL:
+
+- `http://localhost:8080`
+
+### 6) Quick smoke test
+
+Create a conversion request:
+
+```bash
+curl \
+  --header "Content-Type: application/json" \
+  --data '{"sourceFilename":"example.pptx"}' \
+  http://localhost:8080/officeconvertapi.v1.ConversionService/CreateConversion
+```
+
+Then:
+
+1. Upload the PPTX to the returned `uploadUrl` using HTTP `PUT`.
+2. Call `StartConversion` with the returned `conversionId`.
+3. Poll `GetConversionStatus` until `CONVERSION_STATUS_SUCCEEDED`.
+4. Call `GetSlideDeck` and download each `imageUrl`.
+5. Optionally call `DeleteConversion` for early cleanup.
+
+### 7) Full container workflow (optional)
+
+If you want to run both server and MinIO in Docker:
+
+```bash
+make compose-up
+```
+
+Use `.env.example` as your baseline env configuration.