stephengpope · jpatrickfarrell · Mar 4, 2026 · Mar 4, 2026 · Mar 4, 2026 · Mar 4, 2026
diff --git a/.env.example b/.env.example
@@ -48,6 +48,13 @@ API_KEY=your_api_key_here
 # Requirement: Optional.
 #LOCAL_STORAGE_PATH=/tmp
 
+# LOCAL_OUTPUT_PATH
+# Purpose: Where output files are saved when no cloud storage (S3/GCP) is configured.
+# Used with 'make up-local' for local file processing without cloud storage.
+# Default: /data/output (maps to ./local/output on host via volume mount)
+# Requirement: Optional.
+#LOCAL_OUTPUT_PATH=/data/output
+
 # Google Cloud Run Jobs
 # Purpose: Offload long-running tasks to Cloud Run Jobs for scalability
 # Requirement: Optional. Configure if you want to use GCP Cloud Run Jobs.

diff --git a/.gitignore b/.gitignore
@@ -1,4 +1,10 @@
 .env_variables.json
 .DS_Store
 .env_shell.json
-.env
+.env
+local/
+
+# Python bytecode
+__pycache__/
+*.pyc
+*.pyo
diff --git a/Dockerfile b/Dockerfile
@@ -180,11 +180,13 @@ RUN pip install --no-cache-dir --upgrade pip && \
     pip install playwright && \
     pip install jsonschema 
 
-# Create the appuser 
-RUN useradd -m appuser 
+# Create the appuser
+RUN useradd -m appuser
 
 # Give appuser ownership of the /app directory (including whisper_cache)
-RUN chown appuser:appuser /app 
+# Also create local file I/O directories for volume mounts (make up-local)
+RUN chown appuser:appuser /app && \
+    mkdir -p /data/input /data/output && chown appuser:appuser /data/input /data/output
 
 # Important: Switch to the appuser before downloading the model
 USER appuser

diff --git a/Makefile b/Makefile
diff --git a/README.md b/README.md
@@ -124,6 +124,85 @@ Each endpoint is supported by robust payload validation and detailed API documen
 
 ---
 
+## Quick Start with Makefile
+
+The project includes a Makefile that handles building, running, testing, and deploying.
+
+```bash
+# Show all available commands
+make help
+```
+
+### Local Development
+
+```bash
+# 1. Generate .env with auto-generated API key
+make setup
+
+# 2. Edit .env to configure your storage provider (S3 or GCP)
+
+# 3. Build and run
+make up                # With cloud storage
+make up-local          # Or with local file I/O (no cloud storage needed)
+
+# 4. Test
+make test
+
+# 5. Stop
+make down
+```
+
+### Deploy to Google Cloud Run
+
+```bash
+# 1. Authenticate with GCP
+gcloud auth login
+gcloud config set project YOUR_PROJECT_ID
+
+# 2. Generate .env (if not done) and configure storage credentials
+make setup
+
+# 3. One-time GCP project bootstrap — enables APIs, creates registry, configures IAM
+make cloud-setup
+
+# 4. Build on Cloud Build and deploy to Cloud Run (recommended)
+make cloud-deploy
+
+# 5. Verify the deployment
+make test URL=https://your-service-url.run.app
+
+# Override defaults as needed
+make cloud-deploy GCP_PROJECT_ID=my-project GCP_REGION=europe-west1
+```
+
+There are two deploy paths:
+
+| Command | Build Location | Best For |
+|---------|---------------|----------|
+| `make cloud-deploy` | Cloud Build (GCP) | Apple Silicon Macs, CI/CD, production **(recommended)** |
+| `make deploy` | Local Docker | Linux x86 machines with Docker |
+
+See [GCP Deployment Guide](docs/deploy/DEPLOY_GCP.md) for the full walkthrough, or [What's New](docs/WHATS_NEW.md) for a summary of all additions.
+
+### Upload Local Files for Processing
+
+Upload a file directly to the API for processing (no pre-existing URL needed):
+
+```bash
+# Upload via CLI (auto-detects local files)
+python3 tools/nca.py transcribe --file ./video.mp4
+
+# Or upload via API
+curl -X POST http://localhost:8080/v1/files/upload \
+  -H "X-API-Key: YOUR_KEY" \
+  -F "file=@./video.mp4"
+# Returns: {"url": "https://...", "filename": "video.mp4"}
+```
+
+For fully local processing without cloud storage, use `make up-local` which mounts `./local/input/` and `./local/output/` as volume directories.
+
+---
+
 ## Docker Build and Run
 
 ### Build the Docker Image
@@ -260,23 +339,18 @@ If you use the webhook_url, there is no limit to the processing length.
 
 - [Digital Ocean App Platform Installation Guide](https://github.com/stephengpope/no-code-architects-toolkit/blob/main/docs/cloud-installation/do.md) - Deploy the API on Digital Ocean App Platform
 
-### Google Cloud RUN Platform
-
-Sometimes difficult for people to install (especially on Google Business Workspaces), lots of detailed security exceptions.
-
-However this is one of the cheapest options with great performance because you're only charged when the NCA Toolkit is processesing a request.
-
-Outside of that you are not charged.
-
-#### Imporatnt: Requests exceeding 5+ minutes can be problemactic 
+### Google Cloud Run (Recommended)
 
-GCP Run will terminate long rununing processes, which can happen when processing larger files (whether you use the webhook_url or not).
+The cheapest option with great performance — you only pay while requests are being processed. The Makefile automates the entire workflow: `make cloud-setup` then `make cloud-deploy`.
 
-However, when your processing times are consistant lower than 5 minutes (e.g. you're only process smaller files), it works great! The performance is also great and as soon as you stop making requests you stop paying.
+- **[GCP Deployment Guide (Makefile)](docs/deploy/DEPLOY_GCP.md)** — Full walkthrough
+- **[What's New](docs/WHATS_NEW.md)** — Summary of Makefile, Cloud Build, file upload, and CLI additions
+- [Legacy GCP Console Guide](docs/cloud-installation/gcp.md) — Manual setup via the GCP Console
 
-They also have a GPU option that might be usable for better performance (untested).
+#### Notes
 
-- [Google Cloud RUN Platform (GCP) Installation Guide](https://github.com/stephengpope/no-code-architects-toolkit/blob/main/docs/cloud-installation/gcp.md) - Deploy the API on Google Cloud Run
+- Requests exceeding ~5 minutes may be terminated by Cloud Run. Use `webhook_url` or configure [Cloud Run Jobs](docs/deploy/DEPLOY_GCP.md#optional-cloud-run-jobs-for-long-running-tasks) for large files.
+- GPU option available but untested.
 
 ### General Docker Instructions
 

diff --git a/config.py b/config.py
@@ -27,6 +27,9 @@
 # Storage path setting
 LOCAL_STORAGE_PATH = os.environ.get('LOCAL_STORAGE_PATH', '/tmp')
 
+# Local file output path (used when no cloud storage is configured)
+LOCAL_OUTPUT_PATH = os.environ.get('LOCAL_OUTPUT_PATH', '/data/output')
+
 # GCP environment variables
 GCP_SA_CREDENTIALS = os.environ.get('GCP_SA_CREDENTIALS', '')
 GCP_BUCKET_NAME = os.environ.get('GCP_BUCKET_NAME', '')

diff --git a/docs/WHATS_NEW.md b/docs/WHATS_NEW.md
@@ -0,0 +1,194 @@
+# What's New: Makefile, Cloud Deployment, CLI, and Local File Upload
+
+This document summarizes the features added on top of the upstream NCA Toolkit.
+
+---
+
+## Makefile Build System
+
+A complete Makefile replaces manual Docker and gcloud commands with simple one-liners.
+
+### Setup & Config
+
+| Command | Description |
+|---------|-------------|
+| `make setup` | Generate `.env` file with an auto-generated API key |
+| `make connect` | Connect the CLI to a running API instance |
+| `make help` | Show all available commands and current configuration |
+
+### Local Development
+
+| Command | Description |
+|---------|-------------|
+| `make build` | Build Docker image (targets `linux/amd64` for Cloud Run compatibility) |
+| `make up` | Build and start container with cloud storage |
+| `make up-local` | Build and start with local file I/O via volume mounts |
+| `make down` | Stop and remove the container |
+| `make clean` | Stop container and remove the Docker image |
+| `make test` | Test local API health |
+| `make test URL=https://...` | Test a remote deployment |
+
+### GCP Cloud Deployment
+
+| Command | Description |
+|---------|-------------|
+| `make cloud-setup` | **One-time** GCP project bootstrap — enables APIs, creates Artifact Registry, configures IAM and Docker auth |
+| `make cloud-deploy` | Build on Cloud Build (native amd64) and deploy to Cloud Run **(recommended)** |
+| `make cloud-build` | Build image remotely on Cloud Build only |
+| `make deploy` | Build locally, push, and deploy to Cloud Run (cross-compiles on Apple Silicon) |
+| `make logs` | Tail Cloud Run service logs |
+| `make describe` | Show Cloud Run service details |
+
+### Configuration Variables
+
+All can be overridden on the command line (e.g., `make deploy GCP_REGION=europe-west1`):
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `GCP_PROJECT_ID` | Current `gcloud` project | GCP project ID |
+| `GCP_REGION` | `us-central1` | Deployment region |
+| `GCP_REPO` | `nca-toolkit` | Artifact Registry repository name |
+| `IMAGE_NAME` | `no-code-architects-toolkit` | Docker image name |
+| `CLOUD_RUN_SERVICE` | `nca-toolkit` | Cloud Run service name |
+
+---
+
+## Cloud Deployment Workflow
+
+### First-Time Setup (New GCP Project)
+
+```bash
+# 1. Authenticate with GCP
+gcloud auth login
+gcloud config set project YOUR_PROJECT_ID
+
+# 2. Generate .env with API key and configure storage credentials
+make setup
+# Edit .env to add S3 or GCP storage credentials
+
+# 3. One-time GCP project bootstrap
+make cloud-setup
+
+# 4. Build and deploy
+make cloud-deploy
+
+# 5. Verify
+make test URL=https://your-service-url.run.app
+```
+
+### What `make cloud-setup` Does
+
+1. Enables required GCP APIs: Cloud Build, Cloud Run, Artifact Registry, Container Registry
+2. Creates the Artifact Registry Docker repository
+3. Grants IAM permissions to the Cloud Build and Compute service accounts
+4. Configures Docker authentication for pushing images
+
+### What `make cloud-deploy` Does
+
+1. Uploads source to Cloud Build (builds natively on amd64 — no cross-compilation)
+2. Pushes the built image to Artifact Registry
+3. Converts `.env` to YAML and passes all variables to Cloud Run via `--env-vars-file`
+4. Deploys to Cloud Run with production settings (16Gi memory, 4 CPUs, gen2 execution)
+
+### Subsequent Deploys
+
+After initial setup, redeployment is a single command:
+
+```bash
+make cloud-deploy
+```
+
+### Local Build Alternative
+
+If you prefer building locally (slower on Apple Silicon due to cross-compilation):
+
+```bash
+make deploy
+```
+
+---
+
+## Local File Upload and Processing
+
+Two new endpoints enable uploading local files and retrieving processed output without cloud storage.
+
+### `POST /v1/files/upload`
+
+Upload a local file via multipart form data. Returns a cloud storage URL that can be passed to any processing endpoint.
+
+```bash
+curl -X POST http://localhost:8080/v1/files/upload \
+  -H "X-API-Key: YOUR_KEY" \
+  -F "file=@/path/to/video.mp4"
+```
+
+**Response:**
+```json
+{
+  "url": "https://storage.googleapis.com/bucket/uuid.mp4",
+  "filename": "video.mp4"
+}
+```
+
+### `GET /v1/files/content`
+
+Download a processed file from the container's local output directory.
+
+```bash
+curl -X GET "http://localhost:8080/v1/files/content?path=/data/output/result.mp4" \
+  -H "X-API-Key: YOUR_KEY" \
+  --output result.mp4
+```
+
+Security: Only serves files from `/data/output` and `LOCAL_STORAGE_PATH`. Path traversal is blocked.
+
+### Local File I/O Mode (No Cloud Storage)
+
+Run with volume mounts to process files entirely locally:
+
+```bash
+make up-local
+```
+
+This mounts:
+- `./local/input/` → `/data/input` (read-only) — place input files here
+- `./local/output/` → `/data/output` (writable) — processed files appear here
+
+Reference input files as `file:///data/input/yourfile.mp4` in API requests.
+
+---
+
+## CLI Tool (`tools/nca.py`)
+
+A Python CLI client for interacting with the API from the command line.
+
+### Setup
+
+```bash
+# Connect to a running API instance (interactive)
+make connect
+# — or —
+python3 tools/nca.py connect
+```
+
+### Key Commands
+
+```bash
+# Test connectivity
+python3 tools/nca.py test
+
+# Transcribe a media file (local or URL)
+python3 tools/nca.py transcribe --file ./video.mp4
+python3 tools/nca.py transcribe --url https://example.com/video.mp4
+
+# Run in background with webhook-style polling
+python3 tools/nca.py transcribe --file ./video.mp4 --bg
+
+# Output as JSON
+python3 tools/nca.py transcribe --file ./video.mp4 --json
+
+# Save output to file
+python3 tools/nca.py transcribe --file ./video.mp4 --output-file result.txt
+```
+
+The CLI auto-detects local files vs URLs. When given a local file, it uploads via `/v1/files/upload` first, then passes the resulting URL to the processing endpoint.