update docs for running natively vs in Docker (#113)

docker-compose.native.yml

@@ -0,0 +1,31 @@
+# docker-compose.yml
+# see server/README.md for usage details
+services:
+  kafka:
+    restart: always
+    image: bitnami/kafka
+    ports:
+      - "9093:9093"
+    volumes:
+      - "./server/kafka-data:/bitnami"
+    environment:
+      - KAFKA_ENABLE_KRAFT=yes
+      - KAFKA_CFG_PROCESS_ROLES=broker,controller
+      - KAFKA_CFG_CONTROLLER_LISTENER_NAMES=CONTROLLER
+      - KAFKA_CFG_LISTENERS=PLAINTEXT://:9093,CONTROLLER://:2181
+      - KAFKA_CFG_LISTENER_SECURITY_PROTOCOL_MAP=CONTROLLER:PLAINTEXT,PLAINTEXT:PLAINTEXT
+      #  note this difference from docker-compose.yml
+      #- KAFKA_CFG_ADVERTISED_LISTENERS=PLAINTEXT://kafka:9093
+      - KAFKA_CFG_ADVERTISED_LISTENERS=PLAINTEXT://127.0.0.1:9093
+      - KAFKA_BROKER_ID=1
+      - [email protected]:2181
+      - ALLOW_PLAINTEXT_LISTENER=yes
+      - KAFKA_CFG_NODE_ID=1
+      - KAFKA_KRAFT_CLUSTER_ID=MkU3OEVBNTcwNTJENDM2Qk
+      - KAFKA_CFG_AUTO_CREATE_TOPICS_ENABLE=false
+  redis:
+    image: redis:alpine
+    ports:
+      - "6379:6379"
+    healthcheck:
+      test: [ "CMD", "redis-cli", "ping" ]

server/.env.example

@@ -1 +1 @@
-KAFKA_BOOTSTRAP_SERVERS="kafka:9093"
+KAFKA_BOOTSTRAP_SERVERS="localhost:9093"

server/README.md

@@ -1,34 +1,54 @@
-# run in Docker
+# how to use
+
+Once running, see `http://localhost:30001/docs` for API documentation.
+
+# run natively
 
-## setup config
+Run `poetry install` first if you have not already done so.
+
+## start kafka and redis
 
 ```bash
-cp .env.example .env
+cd ..
+docker-compose -f docker-compose.native.yml up
 ```
 
-## set environment variables
+## start app
 
-- AWS creds:
 ```bash
+# set env vars
+cp .env.example .env
+# set AWS creds (only if S3 access needed)
 eval "$(aws configure export-credentials --profile <YOUR_PROFILE> --format env)"
+# start app
+poetry run uvicorn app:app --host 0.0.0.0 --port 30001
 ```
 
-## run
+## start celery workers
 
 ```bash
-# from repo root
-docker-compose up
+# set AWS creds (only if S3 access needed)
+eval "$(aws configure export-credentials --profile <YOUR_PROFILE> --format env)"
+# start celery workers
+cd tasks/
+poetry run celery -A process_file worker --loglevel=info
 ```
 
+# run in Docker
 
-## rebuild and run on code change
+```bash
+# set AWS creds (only if S3 access needed)
+eval "$(aws configure export-credentials --profile <YOUR_PROFILE> --format env)"
+```
+
+Edit the env variables in `docker-compose.yml` if needed - the defaults should be ok. There should be differences from the `.env` file for native use.
 
 ```bash
 # from repo root
-docker-compose up --build
+docker-compose up
 ```
 
-## run client
+# run client (unused, for dev convenience only)
 
 ```bash
 cd ui/
@@ -37,6 +57,16 @@ yarn start
 
 # development
 
+## rebuild on code change
+
+```bash
+# from repo root
+docker-compose up --build
+# if dependencies have changed, or to get to a clean state:
+docker-compose build --no-cache
+docker-compose up
+```
+
 ## edit client on API change
 
 ```bash