144 lines
3.6 KiB
Markdown
144 lines
3.6 KiB
Markdown
# beatmatchr backend
|
|
|
|
A lightweight FastAPI service that powers beatmatchr. This guide walks through
|
|
the steps required to run the backend locally.
|
|
|
|
## Prerequisites
|
|
|
|
- Python 3.10 or newer installed and available on your `PATH`.
|
|
- [`ffmpeg`](https://ffmpeg.org/) installed (macOS: `brew install ffmpeg`,
|
|
Ubuntu/Debian: `sudo apt install ffmpeg`).
|
|
- Docker and Docker Compose (v2) for running Postgres and Redis.
|
|
|
|
## 1. Create and activate a virtual environment
|
|
|
|
```bash
|
|
python3 -m venv .venv
|
|
source .venv/bin/activate # Windows: .venv\Scripts\activate
|
|
```
|
|
|
|
## 2. Install Python dependencies
|
|
|
|
With the virtual environment active, install the requirements:
|
|
|
|
```bash
|
|
pip install --upgrade pip
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
## 3. Start Postgres and Redis via Docker Compose
|
|
|
|
A `docker-compose.yml` file is provided at the repository root. Launch the
|
|
services in the background:
|
|
|
|
```bash
|
|
docker compose up -d
|
|
```
|
|
|
|
This spins up:
|
|
|
|
- Postgres on port `5432` with database/user/password `beatmatchr`.
|
|
- Redis on port `6379` for task queue usage.
|
|
|
|
If you need to tear everything down (including volumes), run:
|
|
|
|
```bash
|
|
docker compose down -v
|
|
```
|
|
|
|
## 4. Configure environment variables
|
|
|
|
Export environment variables that the backend expects. The defaults line up with
|
|
`docker-compose.yml`, so you can simply create a `.env` file (or export them in
|
|
your shell):
|
|
|
|
```bash
|
|
export POSTGRES_USER=beatmatchr
|
|
export POSTGRES_PASSWORD=beatmatchr
|
|
export POSTGRES_DB=beatmatchr
|
|
export POSTGRES_HOST=localhost
|
|
export POSTGRES_PORT=5432
|
|
export REDIS_HOST=localhost
|
|
export REDIS_PORT=6379
|
|
export REDIS_DB=0
|
|
export CELERY_BROKER_URL=redis://localhost:6379/0
|
|
export CELERY_RESULT_BACKEND=redis://localhost:6379/0
|
|
```
|
|
|
|
Feel free to adjust these if you change the Docker Compose configuration.
|
|
|
|
## 5. Run database migrations / initialize tables
|
|
|
|
If you have Alembic migrations configured, apply them with:
|
|
|
|
```bash
|
|
alembic upgrade head
|
|
```
|
|
|
|
If migrations are not available yet, you can run your project-specific database
|
|
bootstrap script (for example `python -m backend.db init_db`) to create tables
|
|
manually. Ensure the `DATABASE_URL` environment variable is pointing at the
|
|
Postgres instance from the Docker Compose stack.
|
|
|
|
## 6. Start the FastAPI application
|
|
|
|
Launch the app with `uvicorn` (hot reload optional):
|
|
|
|
```bash
|
|
uvicorn backend.main:app --reload
|
|
```
|
|
|
|
The API will be available at <http://localhost:8000/>.
|
|
|
|
## 7. Start the Celery/RQ worker
|
|
|
|
For Celery, point to the Celery app defined in your project (replace the module
|
|
path if needed):
|
|
|
|
```bash
|
|
celery -A backend.worker.celery_app worker --loglevel=info
|
|
```
|
|
|
|
If you are using RQ instead of Celery, start a worker referencing the same Redis
|
|
instance:
|
|
|
|
```bash
|
|
rq worker beatmatchr --url redis://localhost:6379/0
|
|
```
|
|
|
|
## 8. Example API usage
|
|
|
|
Replace `PROJECT_ID` with the UUID returned from the *create project* call.
|
|
|
|
### Create a project
|
|
|
|
```bash
|
|
curl -X POST "http://localhost:8000/projects" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"name": "Demo Project", "description": "My first beatmatch"}'
|
|
```
|
|
|
|
### Upload audio to a project
|
|
|
|
```bash
|
|
curl -X POST "http://localhost:8000/projects/PROJECT_ID/audio" \
|
|
-F "file=@/path/to/local/file.wav"
|
|
```
|
|
|
|
### Add a source clip by URL
|
|
|
|
```bash
|
|
curl -X POST "http://localhost:8000/projects/PROJECT_ID/sources" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"url": "https://example.com/audio.mp3", "start": 0, "end": 30}'
|
|
```
|
|
|
|
### Fetch lyrics for a track
|
|
|
|
```bash
|
|
curl "http://localhost:8000/projects/PROJECT_ID/lyrics"
|
|
```
|
|
|
|
With the services running and environment variables configured, you should be
|
|
able to follow the steps above to interact with the beatmatchr backend locally.
|