OpenLabs API

Table of Contents

1. Quickstart
2. Project Structure
3. Environment Setup
4. Tests
5. Debugging
6. Workflows
7. Contributing
8. License

Quickstart

Clone the repo:

git clone https://github.com/OpenLabsHQ/API.git

Copy the ENV example:

cd API/
cp .env.example .env

Start the docker compose:

docker compose up --build

Congrats! It's working! 🎉

• API Documentation: http://127.0.0.1:8000/docs
• OpenLabs Docs: https://docs.openlabs.sh/

Project Structure

src/
├── app
│   ├── api                 # API routes
│   ├── core
│   │   ├── auth
│   │   ├── cdktf           # Terraform CDKTF logic
│   │   │   ├── hosts   
│   │   │   ├── ranges
│   │   │   ├── stacks
│   │   │   ├── subnets
│   │   │   └── vpcs
│   │   └── db              # Database configuration
│   ├── crud
│   ├── enums               # User options
│   ├── logs
│   ├── middlewares
│   ├── models              # ORM models
│   ├── schemas             # API/Pydantic schemas
│   ├── utils
│   ├── validators
│   └── main.py             # Application entry point
│
└── scripts                 # Setup scripts

Environment Setup

Create environment:

python3.12 -m venv venv

Activate environment:

source venv/bin/activate

Install dependencies:

pip install --upgrade pip
pip install -r requirements.txt
pip install -r dev-requirements.txt

Tests

Run tests:

# Unit tests
pytest -m unit

# Integration tests (no deployments)
pytest -m "integration and not deploy"

# Configure provider credentials
cp .env.tests.example .env.tests

# Provider specific tests
pytest -m aws

See marks defined in pyproject.toml for more options.

Code coverage:

open htmlcov/index.html

Test session logs:

# Pytest logs (fixture setup)
pytest_run.log

# Integration tests docker log
docker_compose_test_*.log

All test related logs are stored in .testing-out/.

Test Organization

All tests are located in tests/ with each subdirectory mirroring src/app/:

• unit - Unit tests.
• integration - Integration tests (docker compose).
• common - Tests shared by unit and integration test suites.

Debugging

To debug with the docker compose:

docker compose -f docker-compose.yml -f docker-compose.dev.yml up

The app will only be started once you run the debugger in VScode using the Python: Remote Attach to OpenLabs API profile.

Workflows

Quality Gates

• black.yml - Runs the Black code formatter in check mode to verify code formatting.
• ruff.yml - Runs the Ruff linter to check for code quality issues.
• mypy.yml - Performs static type checking with MyPy.
• unit_tests.yml - Runs all unit tests.
• integration_tests.yml Runs integration tests that do not deploy live infrastructure.
• aws_tests.yml - Run all AWS specific tests including live deploy tests.

Release Management

• check_pr_labels.yml - Checks for properly labeled PRs required by auto_release.yml.
• auto_release.yml - Creates GitHub tagged releases based on the tag of the PR.