document run server workflow

Makefile

@@ -2,7 +2,7 @@ SHELL := /bin/sh
 
 BUF ?= buf
 
-.PHONY: buf-lint buf-generate py-sync go-test compose-up compose-up-dev
+.PHONY: buf-lint buf-generate py-sync go-test compose-up compose-up-dev run-server
 
 buf-lint:
 	$(BUF) lint
@@ -21,3 +21,17 @@ compose-up:
 
 compose-up-dev:
 	docker compose --env-file .env.example -f deploy/docker-compose.dev.yml up
+
+run-server:
+	@set -a; \
+	if [ -f .env ]; then . ./.env; fi; \
+	set +a; \
+	export PYTHONPATH="$${PYTHONPATH:-gen/python:python/packages/officeconvert/src:python/packages/server/src}"; \
+	export MINIO_ENDPOINT="$${MINIO_ENDPOINT:-localhost:9000}"; \
+	export MINIO_PUBLIC_ENDPOINT="$${MINIO_PUBLIC_ENDPOINT:-localhost:9000}"; \
+	export MINIO_USE_SSL="$${MINIO_USE_SSL:-false}"; \
+	export MINIO_ACCESS_KEY="$${MINIO_ACCESS_KEY:-minioadmin}"; \
+	export MINIO_SECRET_KEY="$${MINIO_SECRET_KEY:-minioadmin}"; \
+	export MINIO_SESSION_TTL_SECONDS="$${MINIO_SESSION_TTL_SECONDS:-3600}"; \
+	export CONVERSION_CLEANUP_DELAY_SECONDS="$${CONVERSION_CLEANUP_DELAY_SECONDS:-3600}"; \
+	uv run --project python uvicorn officeconvert_server.app:app --host "$${UVICORN_HOST:-0.0.0.0}" --port "$${UVICORN_PORT:-8080}"

README.md

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