Qernel

Qernel is a local AI workspace for generating, adapting, and shipping software faster.

---

Table of contents

• 1. Overview
  • 1.1. Project structure
• 2. Usage
  • 2.1. With Docker (Recommended)
    • 2.1.1. Requirements
    • 2.1.2. Start Docker
  • 2.2. Manual
    • 2.2.1. Requirements
    • 2.2.2. Setup
    • 2.2.3. Start the API
• 3. Development
  • 3.1. With Docker (Recommended)
    • 3.1.1. Requirements
    • 3.1.2. Start Docker
• 4. Appendix
  • 4.1. Useful commands
  • 4.2. Database migrations
• 5. How to contribute
• 6. License

🔭 1. Overview

1.1. Project structure

.
├─ api/
│   ├── routers/                            <-- FastAPI routers
│   │   └── ...
│   ├── app.py                              <-- FastAPI app initialization
│   ├── main.py                             <-- API entrypoint and server start
│   └── ...
├─ build/
│   ├── package/                            <-- Docker image files
│   │   ├── <service-name>/
│   │   │   ├── Dockerfile
│   │   │   └── Dockerfile.development
│   │   └── ...
│   └── ...
├─ deployments/                             <-- Container orchestration configurations
│   ├── compose.yml
│   └── compose.development.yml
├─ registry/                                <-- Manifests
│   ├── feature-packs/                      <-- Feature pack manifests, e.g. "postgres", "auth-jwt"
│   │   ├── <feature_pack>/
│   │   │   └── pack.yml
│   │   └── ...
│   ├── templates                           <-- App template manifests, e.g. "next-fastapi-saas"
│   │   ├── <template_name>/
│   │   │   ├── files/
│   │   │   │   └── ...
│   │   │   └── template.yml
│   │   └── ...
│   └── ...
├─ test/                                    <-- Test utilities and mocks
│   └── ...
├─ web/
│   ├── main.ts                             <-- Web UI entrypoint
│   └── ...
├── dev-requirements.txt                    <-- Python development dependencies
├── LICENSE                                 <-- Project license
├── Makefile                                <-- Make commands
├── pip-requirements.txt                    <-- Defines the pip version
├── pyproject.toml                          <-- Python project configuration file
├── README.md
├── requirements.txt                        <-- Python dependencies
└── ...

^{Back to top ^}

🪄 2. Usage

2.1. With Docker (Recommended)

2.1.1. Requirements

• Docker

^{Back to top ^}

2.1.2. Start Docker

1. Using Docker compose, you can run the orchestration file using:

$ make start

^{Back to top ^}

2.2. Manual

2.2.1. Requirements

• Python v3.11+
• Make

^{Back to top ^}

2.2.2. Setup

Install the dependencies and tools:

$ make install

^{Back to top ^}

2.2.3. Start the API

Start the API (this will use a Python virtual environment):

$ make run_api

^{Back to top ^}

🛠️ 3. Development

3.1. With Docker (Recommended)

3.1.1. Requirements

• Docker

^{Back to top ^}

3.1.2. Start Docker

1. Using Docker compose, you can run the orchestration file using:

$ make dev

^{Back to top ^}

📑 4. Appendix

4.1. Useful commands

Command	Description
make dev	Runs the platform in development mode via Docker.
make format	Formats soruce code files.
make install	Installs all the dependencies - including development dependencies.
make install_js_deps	Installs the JavaScript dependencies.
make install_py_deps	Installs the Python application dependencies.
make install_py_dev	Installs the Python dependencies that inlucde tools for development.
make lint_py	Lints Python soruce files.
make run_api	Starts the API in the Python virtual environment.
make run_web	Starts the web application.
make start	Runs the platform in production mode via Docker.
make test	Runs all tests.
make test_py_unit	Runs Python tests.
make test_unit	Runs all unit tests.

^{Back to top ^}

4.2. Database migrations

Database migrations are managed with Alembic and run through Docker, so they use the same environment as the API service.

Use the following commands to create, apply, or roll back migrations:

make create_migration MESSAGE="adds boats_profiles table"
make database_upgrade
make database_downgrade

For development, the matching commands are:

make database_upgrade_dev
make database_downgrade_dev

• create_migration generates a new Alembic revision from SQLAlchemy model changes.
• database_upgrade applies all pending migrations in the production Compose setup.
• database_downgrade rolls back the latest migration in the production Compose setup.
• database_upgrade_dev applies all pending migrations in the development Compose setup.
• database_downgrade_dev rolls back the latest migration in the development Compose setup.

⚠️ NOTE: The MESSAGE argument is required when creating a migration because it becomes the migration description.

^{Back to top ^}

👏 5. How to contribute

Please read the contributing guide to learn about the development process.

^{Back to top ^}

📄 6. License

Please refer to the COPYING file.

^{Back to top ^}