From 2669af6cf11ed8f15b919c39eeb5bbaa207bbf3f Mon Sep 17 00:00:00 2001 From: stephan Date: Thu, 4 Dec 2025 22:48:33 +0100 Subject: [PATCH] docs: Update README with container registry workflow This commit updates the main README.md file to reflect the recent changes related to the container registry integration. - Clarifies the difference between Starting development environment by pulling image from registry... export IMAGE_NAME=audio-engine-hub && \ export REGISTRY=git.wlkns.org && \ export USERNAME=stephan && \ export TAG=latest && \ docker compose up -d (for registry images) and Starting development environment (local build) on port 8000... (for local builds). - Adds a dedicated "Container Registry" section explaining the push/pull workflow. - Updates the "Makefile Commands" section with the new , , and targets. --- README.md | 60 ++++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 48 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index bfea282..fcee3fe 100644 --- a/README.md +++ b/README.md @@ -8,16 +8,19 @@ AudioEngineHub is a local-first, modular, multi-engine Text-to-Speech (TTS) serv - **Configurable Engines:** Activate or deactivate engines on the fly via a simple configuration file. - **Caching:** Caches generated audio to save resources and provide faster responses for repeated requests. - **Dockerized:** Runs in a containerized environment for easy setup and dependency management. -- **Automatic Port Finding:** Automatically finds and uses a free port, preventing conflicts. +- **Automatic Port Finding:** Automatically finds and uses a free port when building locally. +- **Container Registry Support:** Pre-configured to push to and pull from a container registry. ## Getting Started +This guide covers local development. For information on using the container registry, see the "Container Registry" section below. + ### Prerequisites - [Docker](https://docs.docker.com/get-docker/) - [Docker Compose](https://docs.docker.com/compose/install/) -### Installation +### Local Development Setup 1. **Clone the repository:** ```bash @@ -36,20 +39,50 @@ AudioEngineHub is a local-first, modular, multi-engine Text-to-Speech (TTS) serv ``` 3. **Build and start the container:** - Use the `make up` command to build the Docker image and start the service. + Use the `make dev-up` command to build the Docker image from your local source and start the service. ```bash - make up + make dev-up ``` - This command will automatically find a free port starting from 8000 and run the application on it. + This command will automatically find a free port, build the image, and run the application. > **Note:** For the most reliable port detection, it is recommended to run the command with `sudo`: > ```bash - > sudo make up + > sudo make dev-up > ``` -## Usage +## Container Registry -The application provides a simple API to generate speech and inspect the available engines. +The project is configured to work with the container registry at `git.wlkns.org`. + +### Pushing an Image + +1. **Log in to the Registry:** + You only need to do this once per machine. + ```bash + docker login git.wlkns.org + ``` + +2. **Push the Image:** + This command will build your image, tag it correctly, and push it to the registry. + ```bash + make push + ``` + +### Pulling and Running an Image + +1. **Pull the Image:** + To download the latest image from the registry: + ```bash + make pull + ``` + +2. **Run the Image:** + This command will start the application using the pre-built image from the registry (pulling it if necessary). + ```bash + make up + ``` + +## Usage ### Endpoints @@ -57,16 +90,19 @@ The application provides a simple API to generate speech and inspect the availab - `GET /health`: Check the health of the API and the status of the loaded engines. - `GET /engines`: List the currently active engines. - `GET /models`: List the available models for each active engine. -_ `GET /speakers`: List the available speakers for a given engine and model. +_ `GET /speakers`: List the available speakers for a given engine and model. ### Makefile Commands The project includes a `Makefile` with several commands to simplify development and management: -- `make up`: Build the image and start the application container. -- `make down`: Stop the application container. +- `make dev-up`: Build the image from local source and start the application. Recommended for development. +- `make up`: Start the application using the image from the container registry (pulls if not present). +- `make down`: Stop the application container(s). - `make logs`: View the application logs. - `make health-check`: Run a sanity check to ensure the deployed container is healthy and all engines are "ok". +- `make pull`: Pull the latest image from the container registry. +- `make push`: Build, tag, and push the image to the container registry. - `make test`: Run the `pytest` test suite. - `make help`: Display a list of all available commands. @@ -77,4 +113,4 @@ The application is configured through the `.env` file in the root of the project - `ACTIVE_ENGINES`: A comma-separated list of strings specifying which TTS engines to activate. Available engines are defined in `app/main.py`. - `HOST`: The host address for the server (defaults to `0.0.0.0`). - `PORT`: The internal port for the server (defaults to `8000`). -- `IMAGE_NAME`: The name of the Docker image to build (defaults to `audioenginehub`). \ No newline at end of file +- `IMAGE_NAME`: The name of the Docker image to build (defaults to `audioenginehub`).