Serve Hydra for Studio and the API
Start the local Hydra API on the cumulative workspace, open its generated documentation, and prove readiness with the health endpoint.
1. Objective
Goal
Use hdrctl serve with an explicit host, port, and workspace. Confirm Uvicorn startup, request /api/health, and stop the development server cleanly when the verification is complete.
Keep working from the cli-course folder. The job is named first-job, and the workflow lessons add workflow.yaml beside it; every command and terminal excerpt in this lesson was run against that same cumulative project.
Reading a result. Durations and process identifiers vary between machines — ignore them. What proves a run is the stable evidence: named files, resolved identifiers, row counters, step states, HTTP status. If one of those differs from the lesson, fix the previous step before continuing.
Prerequisites
- Lesson 10 completed and checked.
- The validated
first-jobCSV project. - A terminal opened in the
cli-coursefolder.
2. Steps
01Review the server options
Objective
Choose the bind address, port, and workspace from documented flags.
Actions
- Open the serve help.
- Keep the loopback host for local-only access.
- Use the course folder as the explicit workspace.
hdrctl serve --help
The help lists host, port, reload, and workspace; the default bind is loopback on port 5678.
Options: --host TEXT Adresse d'écoute. [default: 127.0.0.1] --port INTEGER Port d'écoute. [default: 5678] --reload Hot-reload (dev uniquement). --workspace TEXT Répertoire racine des projets Studio
02Start the API
Objective
Launch FastAPI against the cumulative course workspace.
Actions
- Run the server from the Hydra repository environment.
- Bind to
127.0.0.1and the observed test port5689. - Leave this terminal open while the server runs.
hdrctl serve --host 127.0.0.1 --port 5689 --workspace C:\Users\DELL\Desktop\Hydra\conversation_files\cli-course
Hydra prints the API and documentation URLs, then Uvicorn confirms startup.
🚀 Hydra API démarrée sur http://127.0.0.1:5689 📚 Docs disponibles sur http://127.0.0.1:5689/docs INFO: Started server process [18364] INFO: Waiting for application startup. INFO: Application startup complete. INFO: Uvicorn running on http://127.0.0.1:5689 (Press CTRL+C to quit)
03Verify application health
Objective
Prove the running FastAPI application answers its health route.
Actions
- Open a second PowerShell terminal.
- Request the local health endpoint.
- Read both the HTTP status and response body.
Invoke-WebRequest -UseBasicParsing http://127.0.0.1:5689/api/health
The observed request returns HTTP 200 and Hydra's running message.
StatusCode : 200
Content : {"message":"Hydra ETL API is running"}04Close the development server
Objective
Stop the foreground process without leaving the port occupied.
Actions
- Return to the terminal running Uvicorn.
- Press Ctrl+C once.
- Wait for shutdown before closing the terminal.
Ctrl+C
The foreground server exits and the shell prompt returns; a later serve command can reuse the port.
3. Checklist
| Verification | Expected result |
|---|---|
| Bind address | 127.0.0.1:5689 |
| Docs URL | http://127.0.0.1:5689/docs |
| Health status | HTTP 200 |
| Health body | {"message":"Hydra ETL API is running"} |
4. Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| Uvicorn is not installed | The optional API dependency is absent | Install the repository requirements, then run the same serve command |
| The port is already in use | Another process owns port 5689 | Stop that process or choose another explicit port and update the health URL |
| Health cannot connect | The server stopped or the URL differs from the bind arguments | Keep the first terminal running and copy the printed address exactly |
5. Next lesson
You have completed the cumulative CLI track: one job was scaffolded, validated, tested, executed, observed, parameterized, inventoried, orchestrated, and finally served through Hydra's API. Return to the course map or continue with the Studio track over the same workspace.