From 386b15ce946d7c01dd99ae84d0e4161dc4f80d19 Mon Sep 17 00:00:00 2001 From: Ben Date: Wed, 12 Aug 2026 17:49:55 +0200 Subject: [PATCH] Clarify Docker install steps in the README. Make setup a numbered walkthrough covering env, APP_KEY generation, compose up, and verification. --- README.md | 197 +++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 144 insertions(+), 53 deletions(-) diff --git a/README.md b/README.md index 50ff36f..4b2368b 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # AndyTranscribe -Upload pocket-recorder audio (MP3, WAV, OGG, and more), extract embedded metadata, and transcribe locally with [faster-whisper-server](https://github.com/fedirz/faster-whisper-server) via Docker. Audio never leaves your machine. +Upload pocket-recorder audio (MP3, WAV, OGG, and more), extract embedded metadata, and transcribe locally with [faster-whisper-server](https://github.com/fedirz/faster-whisper-server). Audio never leaves your machine. Built with Laravel 13, Blade, Alpine.js, Tailwind CSS 4, [Laravel Reverb](https://laravel.com/docs/reverb), FrankenPHP, and [Laravel AI](https://github.com/laravel/ai). @@ -16,31 +16,110 @@ Built with Laravel 13, Blade, Alpine.js, Tailwind CSS 4, [Laravel Reverb](https: ## Requirements -- [Docker](https://docs.docker.com/get-docker/) and Docker Compose (primary way to run the app) -- For native PHP development: PHP 8.3+ (8.5 recommended), Composer, Node.js & npm, SQLite +- [Docker](https://docs.docker.com/get-docker/) and Docker Compose +- About 2 GB free disk for the Whisper model cache (first run downloads the model) -## Quick start (Docker + FrankenPHP) +Optional for native PHP development: PHP 8.3+ (8.5 recommended), Composer, Node.js & npm. + +## Install + +These steps run the full stack with Docker: web app, queue worker, Reverb WebSockets, and Whisper. + +### 1. Clone the repository + +```bash +git clone andyTranscibe +cd andyTranscibe +``` + +### 2. Create your environment file ```bash cp .env.example .env -# Set a key (required by the app container): -php artisan key:generate # or: docker run --rm -v "$PWD":/app -w /app composer:2 php artisan key:generate - -docker compose up --build ``` -Open [http://localhost:8080/recordings](http://localhost:8080/recordings). +### 3. Generate an application key + +`APP_KEY` is required. Containers refuse to start if it is empty. + +**Option A — PHP installed on the host** + +```bash +php artisan key:generate +``` + +**Option B — Docker only** + +Print a key: + +```bash +docker run --rm php:8.5-cli php -r "echo 'base64:'.base64_encode(random_bytes(32)), PHP_EOL;" +``` + +Open `.env` and set: + +```env +APP_KEY=base64:paste-the-value-here +``` + +On Linux you can write it in one step: + +```bash +KEY=$(docker run --rm php:8.5-cli php -r "echo 'base64:'.base64_encode(random_bytes(32));") +sed -i "s|^APP_KEY=.*|APP_KEY=${KEY}|" .env +``` + +### 4. Start the stack + +```bash +docker compose up --build -d +``` + +On first start the app container will: + +- create `database/database.sqlite` if needed +- run migrations +- start FrankenPHP on port **8080** + +Whisper may take a minute or two while the model downloads. + +### 5. Open the app + +| URL | Purpose | +| --- | --- | +| [http://localhost:8080/recordings](http://localhost:8080/recordings) | App UI | +| [http://localhost:8080/up](http://localhost:8080/up) | Health check | + +Live transcription status uses WebSockets on port **8081** (Reverb). Keep that port reachable from your browser. + +### 6. Verify services (optional) + +```bash +docker compose ps +docker compose logs -f app queue whisper reverb +``` + +You should see `app`, `queue`, `reverb`, and `whisper` running. Whisper becomes healthy after `/health` succeeds. + +### Stop / restart + +```bash +docker compose down +docker compose up -d +``` + +Data under `./database`, `./storage/app`, and `./storage/logs` is kept on the host. + +## Services and ports | Service | Host port | Role | | --- | --- | --- | -| `app` | `8080` | FrankenPHP (Laravel) | -| `reverb` | `8081` | WebSockets for live status | -| `whisper` | `8090` | faster-whisper API | -| `queue` | — | `queue:work` for transcription jobs | +| `app` | `8080` | FrankenPHP (Laravel web UI) | +| `reverb` | `8081` | WebSockets for live transcription status | +| `whisper` | `8090` | faster-whisper HTTP API | +| `queue` | — | `php artisan queue:work` for transcription jobs | -### Persistent data mounts - -These host directories are bind-mounted into `app`, `queue`, and `reverb`: +### Persistent data | Host path | Container path | Contents | | --- | --- | --- | @@ -48,7 +127,30 @@ These host directories are bind-mounted into `app`, `queue`, and `reverb`: | `./storage/app` | `/app/storage/app` | Uploaded audio (`private/recordings`) | | `./storage/logs` | `/app/storage/logs` | Application logs | -Whisper model cache uses the named volume `whisper-huggingface-cache`. +Whisper model cache uses the Docker volume `whisper-huggingface-cache`. + +### Useful environment variables + +Edit `.env` before `docker compose up` when you need different ports or models: + +| Variable | Purpose | Default | +| --- | --- | --- | +| `APP_KEY` | Required Laravel encryption key | — | +| `APP_URL` | Public app URL | `http://localhost:8080` | +| `APP_HOST_PORT` | Host port for the web app | `8080` | +| `REVERB_HOST_PORT` | Host port for WebSockets | `8081` | +| `WHISPER_HOST_PORT` | Host port for Whisper | `8090` | +| `LOCAL_WHISPER_MODEL` | Whisper model id | `Systran/faster-whisper-base` | +| `TRANSCRIPTION_TIMEOUT` | Job/HTTP timeout (seconds) | `600` | +| `DB_QUEUE_RETRY_AFTER` | Must exceed `TRANSCRIPTION_TIMEOUT` | `660` | + +Inside Compose, Laravel talks to Whisper at `http://whisper:8000/v1` and publishes broadcasts to the `reverb` service. The browser connects to Reverb on `localhost:8081`. + +If you change `REVERB_APP_KEY` or browser-facing Reverb host/port settings, rebuild so Vite embeds the new values: + +```bash +docker compose up --build -d +``` ### GPU Whisper (optional) @@ -56,58 +158,47 @@ Whisper model cache uses the named volume `whisper-huggingface-cache`. docker compose --profile gpu up -d --build ``` -Point `LOCAL_WHISPER_URL` at the GPU service if you run it instead of the CPU `whisper` service. +Use the GPU Whisper service instead of the CPU `whisper` service when you have an NVIDIA GPU and the NVIDIA Container Toolkit installed. -### Useful Compose env +## Usage -Copy values from `.env.example`. Important Docker-oriented variables: +1. Open **Recordings → Upload** and drop one or many audio files. +2. Transcription starts automatically (the `queue` service must be running). +3. Watch live progress on the list or detail page; stop or restart anytime. +4. Search by title, artist, or transcript text. +5. For older uploads still **Queued** with no progress, use **Queue pending transcriptions** on the recordings list. -| Variable | Purpose | -| --- | --- | -| `APP_KEY` | Required — containers refuse to start without it | -| `APP_URL` | Default `http://localhost:8080` | -| `APP_HOST_PORT` | Host port for FrankenPHP (default `8080`) | -| `REVERB_HOST_PORT` | Host port for Reverb WebSockets (default `8081`) | -| `WHISPER_HOST_PORT` | Host port for Whisper (default `8090`) | -| `REVERB_APP_*` | Reverb credentials (baked into frontend at image build for `VITE_REVERB_*`) | -| `LOCAL_WHISPER_MODEL` | Model name for local transcription | -| `TRANSCRIPTION_TIMEOUT` | Job/HTTP timeout in seconds (default `600`) | - -Inside Compose, Laravel talks to Whisper at `http://whisper:8000/v1` and publishes broadcasts to the `reverb` service. The browser connects to Reverb on `localhost:8081`. - -Stop: - -```bash -docker compose down -``` +Finished transcripts are stored on each recording and are included in search. ## Native PHP development (optional) +For hacking on the Laravel app outside the FrankenPHP image: + ```bash composer setup docker compose up -d whisper reverb -# In separate terminals: +``` + +Then in separate terminals: + +```bash php artisan serve --port=8000 php artisan queue:work php artisan reverb:start npm run dev ``` -Set `APP_URL=http://localhost:8000`, `LOCAL_WHISPER_URL=http://127.0.0.1:8090/v1`, and Reverb `REVERB_HOST=localhost` / `REVERB_PORT=8080` (match `VITE_REVERB_*`). +Point `.env` at local services, for example: -## Configuration - -Finished transcripts are stored on the recording (`transcript` column) and are included in the recordings search box (title, artist, album, filename, and transcript). - -`DB_QUEUE_RETRY_AFTER` must exceed `TRANSCRIPTION_TIMEOUT` so long Whisper jobs are not re-queued mid-run. - -## Usage - -1. **Upload** audio from Recordings → Upload (single file or batch dropzone). -2. Transcription queues automatically — the Compose `queue` service (or `php artisan queue:work`) must be running. -3. Watch live progress on the recordings list or detail page (Reverb); stop and restart anytime. -4. Search the list by title, artist, or transcript text. -5. If older uploads still show **Queued** with no progress, use **Queue pending transcriptions** on the recordings list. +```env +APP_URL=http://localhost:8000 +LOCAL_WHISPER_URL=http://127.0.0.1:8090/v1 +REVERB_HOST=localhost +REVERB_PORT=8080 +VITE_REVERB_HOST=localhost +VITE_REVERB_PORT=8080 +VITE_REVERB_SCHEME=http +``` ## Tests