diff --git a/.env.example b/.env.example
new file mode 100644
index 0000000..b8e0bc0
--- /dev/null
+++ b/.env.example
@@ -0,0 +1,13 @@
+# Dostalgia — Environment Variables
+# Copy this to .env and fill in your values.
+# Source it before running deploy.sh:  source .env && ./deploy.sh
+
+# IGDB (Twitch) credentials — required for game artwork & metadata
+TWITCH_CLIENT_ID=your_client_id_here
+TWITCH_CLIENT_SECRET=your_client_secret_here
+
+# Optional overrides (defaults are fine for most setups)
+# IMAGE_NAME=dostalgia
+# CONTAINER_NAME=dostalgia
+# HOST_PORT=8765
+# DATA_DIR=/opt/data/workspace/dostalgia/data
diff --git a/.gitignore b/.gitignore
index 397063d..fb59cd8 100644
--- a/.gitignore
+++ b/.gitignore
@@ -27,6 +27,9 @@ data/saves/*
 *.ipr
 *.iws
 
+# Environment (credentials)
+.env
+
 # Test/upload artifacts
 *.zip
 *.ZIP
diff --git a/deploy.sh b/deploy.sh
new file mode 100755
index 0000000..f065761
--- /dev/null
+++ b/deploy.sh
@@ -0,0 +1,105 @@
+#!/usr/bin/env bash
+# ────────────────────────────────────────────────────────────
+# dostalgia — Build & Deploy Script
+# ────────────────────────────────────────────────────────────
+# Usage:
+#   ./deploy.sh                    # build & deploy (behind current tag)
+#   ./deploy.sh --tag v1.2.3       # build & deploy with specific tag
+#   ./deploy.sh --no-pull          # skip git pull
+#   ./deploy.sh --help             # show this message
+#
+# This script does the same thing the Gitea Actions workflow does,
+# but can be run manually from the Unraid host (or any machine with
+# Docker access and the repo cloned).
+# ────────────────────────────────────────────────────────────
+
+set -euo pipefail
+
+# ─── Config ─────────────────────────────────────────────────
+IMAGE_NAME="${IMAGE_NAME:-dostalgia}"
+CONTAINER_NAME="${CONTAINER_NAME:-dostalgia}"
+HOST_PORT="${HOST_PORT:-8765}"
+DATA_DIR="${DATA_DIR:-/opt/data/workspace/dostalgia/data}"
+REPO_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+# IGDB credentials (set these in your environment or .env file)
+TWITCH_CLIENT_ID="${TWITCH_CLIENT_ID:-}"
+TWITCH_CLIENT_SECRET="${TWITCH_CLIENT_SECRET:-}"
+
+# ─── Help ───────────────────────────────────────────────────
+if [[ "${1:-}" == "--help" ]]; then
+  sed -n '2,14p' "$0"
+  exit 0
+fi
+
+# ─── Parse args ─────────────────────────────────────────────
+DO_PULL=true
+TAG=""
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --no-pull) DO_PULL=false; shift ;;
+    --tag)     TAG="$2"; shift 2 ;;
+    *)         echo "Unknown: $1"; exit 1 ;;
+  esac
+done
+
+# ─── Pull latest code ───────────────────────────────────────
+if $DO_PULL; then
+  echo "⟳ Pulling latest code from Gitea..."
+  cd "$REPO_DIR"
+  git fetch origin
+  git checkout main
+  git pull origin main
+fi
+
+if [[ -z "$TAG" ]]; then
+  TAG="$(git rev-parse --short HEAD)"
+fi
+
+echo "Building: $IMAGE_NAME:$TAG"
+
+# ─── Build the frontend and backend ─────────────────────────
+echo "🔨 Building Docker image..."
+docker build -t "$IMAGE_NAME:$TAG" "$REPO_DIR"
+docker tag "$IMAGE_NAME:$TAG" "$IMAGE_NAME:latest"
+
+# ─── Stop old container ─────────────────────────────────────
+echo "🛑 Stopping old container..."
+docker stop "$CONTAINER_NAME" 2>/dev/null || true
+docker rm "$CONTAINER_NAME" 2>/dev/null || true
+
+# ─── Start new container ────────────────────────────────────
+echo "🚀 Starting new container..."
+DOCKER_ARGS=(
+  -d
+  --name "$CONTAINER_NAME"
+  --restart unless-stopped
+  -p "$HOST_PORT:8765"
+  -v "$DATA_DIR:/data"
+)
+
+if [[ -n "$TWITCH_CLIENT_ID" && -n "$TWITCH_CLIENT_SECRET" ]]; then
+  DOCKER_ARGS+=(-e "TWITCH_CLIENT_ID=$TWITCH_CLIENT_ID")
+  DOCKER_ARGS+=(-e "TWITCH_CLIENT_SECRET=$TWITCH_CLIENT_SECRET")
+  echo "   IGDB credentials: configured"
+else
+  echo "   IGDB credentials: not set (auto-scrape disabled)"
+  echo "   Set TWITCH_CLIENT_ID and TWITCH_CLIENT_SECRET env vars to enable"
+fi
+
+docker run "${DOCKER_ARGS[@]}" "$IMAGE_NAME:latest"
+
+# ─── Health check ───────────────────────────────────────────
+echo "⏳ Waiting for container to be healthy..."
+sleep 3
+for i in $(seq 1 30); do
+  if curl -sf "http://localhost:$HOST_PORT/api/health" >/dev/null 2>&1; then
+    echo "✅ Dostalgia is running at http://localhost:$HOST_PORT"
+    exit 0
+  fi
+  sleep 2
+done
+
+echo "❌ Health check failed — check logs: docker logs $CONTAINER_NAME"
+exit 1