feat: documentation and readme

README.md

@@ -1,3 +1,70 @@
-# pi-mta-sign
+# Pi MTA Sign!
 
-Code and documentation for project for turning a raspberry pi into your very own MTA subway sign. 
+This project gives you a docker image that you can run locally to pull MTA data and self-host a webpage that looks very
+similar to the classic MTA Signs found in the metro.
+
+Initially designed to run directly on a raspberry pi, it has been containerized and now runs anywhere you can install
+podman or docker!
+
+## Running the Docker Image
+
+### Prerequisites
+
+- Docker installed on your system
+
+### Quick Start with Docker
+
+Pull the latest image from GitHub Container Registry:
+
+```bash
+docker pull ghcr.io/lucasoskorep/pi-mta-sign:latest
+```
+
+Run the container:
+
+```bash
+docker run -d \
+  -p 8000:8000 \
+  --name pi-mta-sign \
+  ghcr.io/lucasoskorep/pi-mta-sign:latest
+```
+
+The application will be available at `http://localhost:8000`
+
+### Environment Variables
+
+| Variable          | Description                     | Default | Required |
+|-------------------|---------------------------------|---------|----------|
+| `FRONTEND_ENABLE` | Enable/disable the web frontend | `true`  | No       |
+
+### Running with Docker Compose
+
+For a more convenient setup, use the provided docker-compose configuration:
+
+```bash
+# Copy the example docker-compose.yaml from the docker folder
+cp docker/docker-compose.example.yaml docker-compose.yaml
+
+# Run with docker-compose
+docker-compose up -d
+```
+
+See `docker/docker-compose.example.yaml` for a complete example configuration.
+
+### Local Development
+
+To develop on this app locally you can clone the repo and then in the repo root run the following
+
+Tools needed:
+
+- [just](https://github.com/casey/just)
+- [uv](https://github.com/astral-sh/uv)
+- [fnm](https://github.com/Schniz/fnm)
+
+Once you have all the required tooling all you need to do is
+
+```bash
+just init # downloads python 
+
+just dev # this will spin up the nextjs frontend and fastapi backend in hot reload mode
+```

docker/docker-compose.example.yaml

@@ -0,0 +1,11 @@
+version: '3.8'
+
+services:
+  pi-mta-sign:
+    image: ghcr.io/lucasoskorep/pi-mta-sign:latest
+    container_name: pi-mta-sign
+    ports:
+      - "8000:8000"
+    environment:
+      # OPTIONAL: Enable or disable the web frontend (default: true)
+      FRONTEND_ENABLE: "true"

justfile

@@ -5,9 +5,7 @@ default:
 # Setup Python project
 init:
     uv sync
-
-# Setup frontend project
-init-ui:
+    fnm use
     cd mta-sign-ui && pnpm install
 
 # Build frontend and run FastAPI serving static files
@@ -21,7 +19,6 @@ dev:
     echo "Starting FastAPI backend on :8000..."
     uv run python main.py &
     BACKEND_PID=$!
-    sleep 2
     echo "Starting Next.js dev server on :3000..."
     cd mta-sign-ui && pnpm dev &
     FRONTEND_PID=$!